Pāriet uz galveno saturu
Latviešu— Izvēlēties valodu
Izvēlne

Utilitaires de conversion audio en Python

Nodarbība 16 no 16 Atjaunota 2026. gada 30. jūlijs Programmētājs
Šajā lapā
  1. Une bibliothèque d’utilitaires audio
  2. De PCM16 vers base64 et inversement
  3. Rééchantillonnage
  4. Conversion entre G.711 et PCM
  5. Détection du silence côté client
  6. Enregistrement et chargement de fichiers WAV
  7. Galvenās atziņas
  8. Vérifie ta compréhension

Une bibliothèque d’utilitaires audio

Pour construire une application Agent Vocal robuste, tu as besoin de fonctions utilitaires qui convertissent l’audio entre différents formats. Cette leçon rassemble les outils Python essentiels pour le traitement audio en temps réel.

De PCM16 vers base64 et inversement

Voici les deux fonctions que tu utiliseras le plus : encoder l’audio capturé en base64 pour l’envoyer, et décoder l’audio base64 reçu pour le lire.

import base64
import numpy as np

def audio_to_base64(audio_data: np.ndarray) -> str:
    """Converts a float32 numpy array in [-1, 1] to base64 PCM16."""
    audio_int16 = (audio_data * 32767).astype(np.int16)
    return base64.b64encode(audio_int16.tobytes()).decode("utf-8")

def base64_to_audio(base64_audio: str) -> np.ndarray:
    """Converts a base64 PCM16 string to a float32 numpy array."""
    audio_bytes = base64.b64decode(base64_audio)
    audio_int16 = np.frombuffer(audio_bytes, dtype=np.int16)
    return audio_int16.astype(np.float32) / 32768.0

Les utiliser dans le flux de l’Agent Vocal

import pyaudio
import json

# Capture micro → envoi
def capture_and_send(ws, stream, chunk_size=4096):
    raw_data = stream.read(chunk_size, exception_on_overflow=False)
    audio_array = np.frombuffer(raw_data, dtype=np.int16)
    audio_float = audio_array.astype(np.float32) / 32768.0
    b64 = audio_to_base64(audio_float)

    ws.send(json.dumps({
        "type": "input_audio_buffer.append",
        "audio": b64
    }))

# Réception → lecture
def play_received(player_stream, base64_audio):
    audio_float = base64_to_audio(base64_audio)
    audio_int16 = (audio_float * 32767).astype(np.int16)
    player_stream.write(audio_int16.tobytes())

Rééchantillonnage

Si ton microphone capture à une fréquence d’échantillonnage différente de celle attendue par l’API, tu dois rééchantillonner :

from scipy.signal import resample

def resample_audio(
    audio: np.ndarray,
    original_rate: int,
    target_rate: int
) -> np.ndarray:
    """Resamples audio from one sample rate to another."""
    if original_rate == target_rate:
        return audio
    num_samples = int(len(audio) * target_rate / original_rate)
    return resample(audio, num_samples)

# Exemple : micro à 44100 Hz → API à 24000 Hz
audio_44100 = capture_microphone()
audio_24000 = resample_audio(audio_44100, 44100, 24000)
b64 = audio_to_base64(audio_24000)

Conversion entre G.711 et PCM

Pour les intégrations téléphoniques, tu devras convertir entre G.711 et PCM linéaire. Surveille ta version de Python : audioop a été retiré de la bibliothèque standard dans la version 3.13. Sur une version récente de Python, installe le paquet audioop-lts, qui fournit la même interface :

import audioop

def pcm_to_mulaw(pcm_data: bytes) -> bytes:
    """Converts PCM16 to G.711 mu-law."""
    return audioop.lin2ulaw(pcm_data, 2)

def mulaw_to_pcm(mulaw_data: bytes) -> bytes:
    """Converts G.711 mu-law to PCM16."""
    return audioop.ulaw2lin(mulaw_data, 2)

def pcm_to_alaw(pcm_data: bytes) -> bytes:
    """Converts PCM16 to G.711 A-law."""
    return audioop.lin2alaw(pcm_data, 2)

def alaw_to_pcm(alaw_data: bytes) -> bytes:
    """Converts G.711 A-law to PCM16."""
    return audioop.alaw2lin(alaw_data, 2)

Un relais téléphonique complet

Voici un exemple de relais entre un flux SIP G.711 et l’API Voice Agent :

async def relay_sip_to_voice_agent(sip_stream, ws):
    """Relays audio from a SIP call to the Voice Agent API."""
    async for mulaw_chunk in sip_stream:
        # Convertir mu-law → PCM → base64
        pcm_data = mulaw_to_pcm(mulaw_chunk)
        b64 = base64.b64encode(pcm_data).decode("utf-8")

        await ws.send(json.dumps({
            "type": "input_audio_buffer.append",
            "audio": b64
        }))

async def relay_voice_agent_to_sip(ws, sip_stream):
    """Relays the API's audio response to the SIP stream."""
    async for message in ws:
        event = json.loads(message)
        if event["type"] == "response.output_audio.delta":
            pcm_data = base64.b64decode(event["delta"])
            mulaw_data = pcm_to_mulaw(pcm_data)
            await sip_stream.send(mulaw_data)

Détection du silence côté client

Si tu gères toi-même la fonction « push-to-talk » ou si tu souhaites une détection locale du silence avant l’envoi, cette fonction mesure l’énergie du signal :

def is_silence(
    audio: np.ndarray,
    threshold: float = 0.01
) -> bool:
    """Detects whether an audio chunk is silence."""
    rms = np.sqrt(np.mean(audio ** 2))
    return rms < threshold

# Utilisation
audio_chunk = capture_microphone()
if not is_silence(audio_chunk, threshold=0.02):
    b64 = audio_to_base64(audio_chunk)
    ws.send(json.dumps({
        "type": "input_audio_buffer.append",
        "audio": b64
    }))

Enregistrement et chargement de fichiers WAV

Pour le débogage et les tests, tu peux enregistrer et charger des fichiers WAV :

import wave

def save_wav(
    filename: str,
    audio: np.ndarray,
    sample_rate: int = 24000
):
    """Saves a numpy array as a WAV file."""
    audio_int16 = (audio * 32767).astype(np.int16)
    with wave.open(filename, "wb") as wf:
        wf.setnchannels(1)
        wf.setsampwidth(2)
        wf.setframerate(sample_rate)
        wf.writeframes(audio_int16.tobytes())

def load_wav(filename: str) -> tuple[np.ndarray, int]:
    """Loads a WAV file as a float32 numpy array."""
    with wave.open(filename, "rb") as wf:
        sample_rate = wf.getframerate()
        frames = wf.readframes(wf.getnframes())
        audio_int16 = np.frombuffer(frames, dtype=np.int16)
        return audio_int16.astype(np.float32) / 32768.0, sample_rate

Galvenās atziņas

  • audio_to_base64 et base64_to_audio sont les deux fonctions essentielles pour le flux de l’Agent Vocal
  • Le rééchantillonnage est nécessaire lorsque la fréquence d’échantillonnage de ton microphone ne correspond pas à celle de l’API
  • Le module audioop gère les conversions G.711 mu-law et A-law ; il a été retiré de la bibliothèque standard dans Python 3.13, donc installe audioop-lts depuis PyPI sur les versions récentes
  • La détection du silence côté client économise de la bande passante en n’envoyant que l’audio utile
  • Les utilitaires WAV facilitent le débogage en te permettant d’enregistrer et de rejouer des flux audio

Vérifie ta compréhension

WebSocket, VAD, audio : l’agent vocal de bout en bout.

1. Comment configurer une session d'Agent Vocal ?

Réponse : Avec une connexion WebSocket en temps réel, authentifiée avec des jetons éphémères (jamais la clé principale sur le client), puis configurée via session.update et confirmée par session.created et session.updated.

2. Que gère le VAD ?

Réponse : La détection automatique de la parole : il détermine quand l’utilisateur commence et arrête de parler, afin que l’agent sache quand écouter et quand répondre, sans aucun bouton.

3. Comment circule l'audio ?

Réponse : L’entrée sort via input_audio_buffer.append (avec validation et effacement du tampon), et la réponse arrive sous forme d’événements audio à lire, en PCM ou G.711 selon le canal.

4. Que permettent les outils et MCP dans une conversation vocale ?

Réponse : L’appel de fonctions et les outils intégrés (web, X, collections) durant l’échange parlé : l’agent effectue des recherches et agit pendant qu’il parle, événements MCP inclus.

5. Et pour la téléphonie ?

Réponse : SIP et LiveKit avec G.711 : l’agent vocal se connecte au réseau téléphonique, et les utilitaires de conversion audio Python font le pont entre les formats.

Une session sécurisée, le VAD, des tampons bien gérés, des outils en voix : l’assistant téléphonique complet est à ta portée, et ce cours t’a fourni toutes les pièces.