One vs multiple engines
How many engine instances your app needs, and how to wire them into your audio pipeline.
What is
an engine?
An engine is one running instance of the SDK's inference. Each engine loads a model and processes a single audio stream on a single CPU thread. See Vocabulary for the full picture.
Most apps and hardware devices use one Rapidly engine processing audio on the device. Some setups need more than one running in parallel. Below, when one engine is enough and when you might need multiple, on the same device or in the same server instance.
The 90% case: one engine, on device
If your app processes a single audio stream, a phone call, a voice memo, a mic input for dictation, playback audio from a streaming app, you need two things:
- Register your license at startup, before constructing the engine.
- Stop audio, then call close, then release the engine.
That's it. Your audio framework already drives your callback on one thread, so no extra locking is needed.
When you might want more than one engine
Most apps use one engine. Some deliberately use more:
Both directions
Apps that clean both the local mic and the incoming audio run one engine per direction.
Multi-source apps
Apps cleaning several audio sources independently (microphone, game audio, music, voice chat) run one engine per source.
Server-side workloads
Backends processing every guest in a multi-guest session, or splitting a long file into chunks across parallel workers, run one engine per independent input.
Multi-channel inputs: one engine or many?
For embedded hardware with multiple microphones, the unit is the independent input, not the channel. An input can itself be multi-channel.
- All channels belong to one acoustic scene (stereo recording, 5.1 mix, binaural pair, array microphone): one engine, channel count set to match the input.
- Channels are independent inputs (microphones capturing different speakers, separate sources): one engine per input. Each engine handles all the channels of its own input.
| Setup | Engines | Channels each |
|---|---|---|
| Stereo recording | 1 | 2 |
| 5.1 film mix | 1 | 6 |
| Four mono mics, one per speaker | 4 | 1 |
| Four stereo mics, one per speaker | 4 | 2 |
| Binaural pair (one wearer) | 1 | 2 |
Rules for multi-engine apps
Two rules on top of the simple case:
- One thread per engine, one engine per stream. Don't share an engine across threads or streams.
- Register your license once at app startup. It applies to every engine you create afterwards.
When releasing engines that ran in parallel, stop each engine's audio source first, then close, then release.