Interface Audio

L'interface audio relie une session à vos entrées et sorties audio. Elle capture l'audio de l'utilisateur et le transmet au SDK, puis lit l'audio renvoyé par l'agent. Le SDK se charge uniquement du transfert de l'audio entre votre interface et Mistral : la transcription, le modèle et la synthèse vocale s'exécutent chez Mistral.

Cette page concerne Python et Node.js. Dans le navigateur, le SDK capture et lit l'audio pour vous. Consultez Navigateur.

Vous fournissez une interface avec audio_interface (audioInterface en TypeScript) lors de la création de la session. Le SDK la pilote ensuite :

1. Avant la création de la session, le SDK exécute la vérification préalable de l'interface. Si un périphérique ou une bibliothèque audio manque, une erreur se produit avant que Mistral n'alloue une session.
2. Lorsque la session se connecte, le SDK appelle start() pour ouvrir vos périphériques ou vos flux.
3. Dès que l'agent rejoint la session, le SDK lit l'audio de l'utilisateur depuis input_audio() et envoie chaque fragment à Mistral. Lorsque le microphone est désactivé avec set_input_enabled(False), le SDK continue la lecture, mais ignore les fragments.
4. Chaque fois que l'agent parle, le SDK transmet son audio à output_audio(), fragment par fragment.
5. Lorsque la session se ferme, le SDK appelle stop() pour vous permettre de libérer vos ressources.

Audio utilise le même format dans les deux sens :

DefaultAudioInterface enregistre depuis le microphone par défaut du système et lit l'audio sur les haut-parleurs par défaut. En Python, elle utilise PyAudio, qui nécessite PortAudio. En Node.js, elle utilise SoX. Consultez Installer le SDK.

Avant d'envoyer l'audio du microphone, l'interface le nettoie : elle supprime la voix de l'agent captée par le microphone (annulation d'écho), réduit le bruit de fond et uniformise le volume. En sortie, elle met l'audio de l'agent en mémoire tampon et le lit à un rythme régulier. Si l'audio de l'agent arrive plus vite qu'il n'est lu et que le tampon se remplit, l'audio le plus ancien est supprimé.

En Python, ces options permettent de la configurer :

Gardez l'annulation d'écho activée lorsque vous utilisez des haut-parleurs plutôt qu'un casque. Sinon, l'agent risque de s'entendre et de se répondre.

from mistralai.extra.voice_agents import DefaultAudioInterface

audio_interface = DefaultAudioInterface(
    noise_suppression=False,  # The input is already clean
    output_buffer_size_ms=500,
)

from mistralai.extra.voice_agents import DefaultAudioInterface

audio_interface = DefaultAudioInterface(
    noise_suppression=False,  # The input is already clean
    output_buffer_size_ms=500,
)

Pour utiliser une autre source ou destination audio, créez une sous-classe d'AudioInterface (implémentez-la en TypeScript) et fournissez une instance avec audio_interface. Elle comporte quatre méthodes :

from collections.abc import AsyncIterator

from mistralai.extra.voice_agents import AudioInterface

class MyAudioInterface(AudioInterface):
    async def start(self) -> None:
        """Open devices, sockets, or other audio resources."""
        ...

    async def input_audio(self) -> AsyncIterator[bytes]:
        """Yield user audio chunks to send to the agent."""
        ...

    async def output_audio(self, audio: bytes) -> None:
        """Play or forward agent audio."""
        ...

    async def stop(self) -> None:
        """Release resources."""
        ...

session = await client.audio.sessions.init(
    instructions="You are a helpful voice assistant.",
    audio_interface=MyAudioInterface(),
)

from collections.abc import AsyncIterator

from mistralai.extra.voice_agents import AudioInterface

class MyAudioInterface(AudioInterface):
    async def start(self) -> None:
        """Open devices, sockets, or other audio resources."""
        ...

    async def input_audio(self) -> AsyncIterator[bytes]:
        """Yield user audio chunks to send to the agent."""
        ...

    async def output_audio(self, audio: bytes) -> None:
        """Play or forward agent audio."""
        ...

    async def stop(self) -> None:
        """Release resources."""
        ...

session = await client.audio.sessions.init(
    instructions="You are a helpful voice assistant.",
    audio_interface=MyAudioInterface(),
)

En Python, vous pouvez aussi redéfinir preflight(). Le SDK l'appelle avant de créer la session. Si un périphérique manque, l'erreur se produit donc avant l'allocation de la session, et non après. Pour ne modifier qu'une partie du comportement par défaut, créez une sous-classe de l'interface par défaut plutôt que de repartir de zéro.

Si start(), input_audio() ou output_audio() lève une erreur, la session se ferme avec le motif de déconnexion start_failed, audio_input_error ou audio_output_error, respectivement. Si stop() échoue, la session émet un événement error non fatal et se ferme malgré tout.

Si vous ne fournissez pas d'interface audio, la session n'enregistre ni ne lit aucun audio. Une fois la session connectée, envoyez de l'audio à l'agent avec send_audio() (sendAudio() en TypeScript), dans le même format. Recevez l'audio de l'agent via l'événement audio.

session = await client.audio.sessions.init(
    instructions="You are a helpful voice assistant.",
)

async def handle_audio(audio: bytes) -> None:
    ...  # Play or forward agent audio

session.on("audio", handle_audio)

async with session:
    await session.send_audio(audio_bytes)  # 16-bit PCM, mono, 48 kHz
    await session.wait()

session = await client.audio.sessions.init(
    instructions="You are a helpful voice assistant.",
)

async def handle_audio(audio: bytes) -> None:
    ...  # Play or forward agent audio

session.on("audio", handle_audio)

async with session:
    await session.send_audio(audio_bytes)  # 16-bit PCM, mono, 48 kHz
    await session.wait()