Skip to main content

Troubleshooting

Missing SDK license key​

Symptom:

Arctan SDK license key is required; pass license_key or set ARCTAN_SDK_KEY

Fix:

export ARCTAN_SDK_KEY="arc_sk_live_..."

or pass license_key directly to the integration constructor.

SDK license key validation failed​

SDK license key validation happens before audio processing starts. Check that:

  • The SDK license key is valid for the environment.
  • The agent process has outbound HTTPS access.
  • Proxies or firewalls allow outbound HTTPS.
  • System time is accurate.

Sample rate changed​

Symptom:

Audio sample rate changed after Arctan was initialized

Fix the upstream audio source so one processor instance receives one stable sample rate for its lifetime.

Frame does not contain complete processing blocks​

LiveKit frames must contain a whole number of Arctan processing blocks. If the SDK raises a block-alignment error, adjust upstream frame sizing so each frame maps to complete processing blocks at the selected sample rate.

Pipecat buffers partial processing blocks, so any complete-sample chunk size is accepted.

Pipecat returns empty bytes​

ArctanAudioFilter.filter() returns b"" when the current input chunk does not complete one processing block. Pipecat should continue feeding audio; processed bytes are returned when enough audio has been buffered.

Pipecat filter called before start​

Symptom:

ArctanAudioFilter.start() must be called before filter()

The filter is designed to be owned by a Pipecat transport. If you call it manually, call await filter.start(sample_rate) before await filter.filter(audio).

Pipecat odd byte count​

Symptom:

Pipecat audio must contain complete int16 PCM samples

Ensure the transport sends complete PCM16 samples. PCM16 uses two bytes per sample.