> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ai-coustics.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrate from livekit-plugins to livekit-extras

> Move dedicated VAD and Audio Insight from the ai-coustics-maintained plugin 0.2.0 to ai-coustics LiveKit extras 0.25.0.

ai-coustics LiveKit extras replaces the ai-coustics-maintained LiveKit plugin. Extras keeps the dedicated `VAD`, the Tyto `Analyzer` and `FrameProcessorChain`. It does not include speech enhancement. Use the official LiveKit plugin for speech enhancement.

This guide compares plugin 0.2.0 with extras 0.25.0. The extras version matches the version of the ai-coustics core SDK that it uses.

| | Old package | New package |
| - | - | - |
| Python distribution | `ai-coustics-livekit-plugin` | `ai-coustics-livekit-extras` |
| Python import | `livekit.plugins.ai_coustics` | `ai_coustics.livekit` |
| Node.js package | `@ai-coustics/livekit-plugin` | `@ai-coustics/livekit-extras` |
| SDK dependency | `aic-sdk>=3.2.0,<4` / `@ai-coustics/aic-sdk@^0.24.0` | `aic-sdk==3.3.0` / `@ai-coustics/aic-sdk@0.25.0` |
| Source | [ai-coustics/livekit-plugins](https://github.com/ai-coustics/livekit-plugins) | [ai-coustics/livekit-extras](https://github.com/ai-coustics/livekit-extras) |

## What changes

| Feature | Plugin 0.2.0 | Extras 0.25.0 |
| - | - | - |
| Speech enhancement (`Processor`) | Yes | Removed. Use the official plugin. |
| Dedicated VAD (`VAD`) | Yes | Yes, same API |
| Audio Insight (`Analyzer`) | Yes | Yes, same API |
| `FrameProcessorChain` | Yes | Yes, same API |
| Install next to the official plugin | Not in Python | Yes, in both runtimes |

These public names are removed:

* `Processor`, `ProcessorContext` and `ProcessorParameter`
* Node.js only: `ProcessorOptions`, `float32ToPcm16` and `pcm16ToFloat32`

The constructor options of `VAD` and `Analyzer` do not change. VAD defaults, VAD events, analysis events and the OpenTelemetry instrument names do not change. Authentication with `AIC_SDK_LICENSE` or `license_key` / `licenseKey` does not change.

## Migration steps

<Steps>
  <Step title="Replace the package">
    <CodeGroup>
      ```bash Python theme={null}
      pip uninstall ai-coustics-livekit-plugin
      pip install ai-coustics-livekit-extras==0.25.0
      ```

      ```bash Node.js theme={null}
      npm uninstall @ai-coustics/livekit-plugin
      npm install --save-exact @ai-coustics/livekit-extras@0.25.0
      ```
    </CodeGroup>

    In Python, remove the old distribution before you install extras. The old distribution and the official `livekit-plugins-ai-coustics` package write to the same directory. Extras uses a different import path, so it can share an environment with the official plugin.

    Extras pins an exact SDK version. If your project also pins `aic-sdk` or `@ai-coustics/aic-sdk`, change that pin to `3.3.0` or `0.25.0`.
  </Step>

  <Step title="Update the imports">
    Python code that used the `ai_coustics` module object must import names from `ai_coustics.livekit`.

    <CodeGroup>
      ```python Python (before) theme={null}
      from livekit.plugins import ai_coustics

      vad_model = ai_coustics.Model.from_file(vad_path)
      vad = ai_coustics.VAD(model=vad_model)
      analyzer = ai_coustics.Analyzer(model=analysis_model)
      frame_processor = ai_coustics.FrameProcessorChain(vad.processor, analyzer.collector)
      ```

      ```python Python (after) theme={null}
      from ai_coustics.livekit import VAD, Analyzer, FrameProcessorChain, Model

      vad_model = Model.from_file(vad_path)
      vad = VAD(model=vad_model)
      analyzer = Analyzer(model=analysis_model)
      frame_processor = FrameProcessorChain(vad.processor, analyzer.collector)
      ```
    </CodeGroup>

    To keep the module-object style, use `from ai_coustics import livekit as ai_coustics`.

    In Node.js, change only the package name:

    ```ts theme={null}
    import { Analyzer, FrameProcessorChain, Model, VAD } from "@ai-coustics/livekit-extras";
    ```
  </Step>

  <Step title="Move speech enhancement to the official plugin">
    Skip this step if you do not use `Processor`.

    Follow LiveKit's [noise cancellation documentation](https://docs.livekit.io/transport/media/noise-cancellation/) to install and configure the official plugin. Its `audio_enhancement()` / `audioEnhancement()` factory replaces `Processor`. The official plugin selects the model and does not use your provisioned enhancement `.aicmodel` file. Model names do not guarantee identical weights across versions. Compare the output on your own recordings.

    Remove the enhancement model download from your deployment. Keep the VAD and Tyto model downloads.
  </Step>

  <Step title="Rebuild the RoomIO audio path">
    RoomIO has one `noise_cancellation` / `noiseCancellation` slot. The dedicated VAD needs `vad.processor` in that slot, and the Analyzer needs `analyzer.collector` in that slot. The authentication mode of the official plugin controls if the official enhancement can also go in that slot.

    **Explicit ai-coustics authentication.** With `Auth.ai_coustics_api(...)` / `Auth.aiCousticsApi(...)`, the official enhancement does not need LiveKit Cloud credentials or stream information from RoomIO. Put it in the chain after `vad.processor` and `analyzer.collector`. VAD and Tyto then receive the original audio. Self-hosted LiveKit deployments have no LiveKit Cloud credentials, so they require this mode.

    <CodeGroup>
      ```python Python theme={null}
      import os

      from livekit.plugins.ai_coustics import Auth, audio_enhancement
      from ai_coustics.livekit import FrameProcessorChain

      enhancement = audio_enhancement(
          auth=Auth.ai_coustics_api(license_key=os.environ["AIC_SDK_LICENSE"]),
      )
      frame_processor = FrameProcessorChain(vad.processor, analyzer.collector, enhancement)
      ```

      ```ts Node.js theme={null}
      import { Auth, audioEnhancement } from "@livekit/plugins-ai-coustics";
      import { FrameProcessorChain } from "@ai-coustics/livekit-extras";

      const enhancement = audioEnhancement({
        auth: Auth.aiCousticsApi(process.env.AIC_SDK_LICENSE!),
      });
      const frameProcessor = new FrameProcessorChain(vad.processor, analyzer.collector, enhancement);
      ```
    </CodeGroup>

    Omit `analyzer.collector` if you do not use Tyto. ai-coustics bills this enhancement to your SDK key, not through LiveKit Cloud.

    **Default LiveKit Cloud authentication.** The official enhancement needs the LiveKit Cloud credentials that RoomIO gives to the slot. `FrameProcessorChain` does not forward these credentials to its processors. Install the official enhancement in the slot on its own. Thus one session cannot use this mode and the dedicated VAD together. Select one configuration for each session:

    | Old chain | New configuration with LiveKit Cloud authentication |
    | - | - |
    | `vad.processor`, `analyzer.collector`, `processor` | Official enhancement with the official VAD adapter, or extras `FrameProcessorChain(vad.processor, analyzer.collector)` without enhancement |
    | `vad.processor`, `processor` | Official enhancement with the official VAD adapter, or extras `vad.processor` without enhancement |
    | `processor` | Official enhancement only |
    | `vad.processor`, `analyzer.collector` | No change |

    The official VAD adapter is not interchangeable with the dedicated `VAD`. Do not copy the dedicated VAD sensitivity values to the adapter without a review of their ranges. Refer to [Which LiveKit plugin to use](/reference/livekit/plugin-scope) for the differences.
  </Step>

  <Step title="Update logs and metrics filters">
    In Python, the logger name changes from `livekit.plugins.ai_coustics` to `ai_coustics.livekit`. Update log level configuration and log filters that use the old name.

    The OpenTelemetry meter name changes from `ai-coustics-livekit-plugin` to `ai-coustics-livekit-extras` in both runtimes. The instrument names stay the same. Update dashboards that filter on the instrumentation scope.
  </Step>

  <Step title="Check Analyzer shutdown in Node.js">
    `Analyzer.close()` now returns `void`, not a promise. Existing `await analyzer.close()` calls still work. The SDK session ends after an in-flight analysis completes.
  </Step>
</Steps>

## Verify the migration

1. Start a room and confirm that VAD events and `analysisResult` / `analysis_result` events arrive.
2. Disconnect and reconnect, then confirm that a new room produces events again.

## Questions

For extras, open an issue in [ai-coustics/livekit-extras](https://github.com/ai-coustics/livekit-extras/issues). Include package versions, runtime, operating system, model IDs, audio geometry and a redacted error. For the official integration, use [LiveKit's documentation and community](https://docs.livekit.io/home/get-started/intro-to-livekit/).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.