Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Utilitajiet ta' konverżjoni tal-awdjo f'Python

Lezzjoni 16 / 16 Aġġornat 30 ta’ Lulju 2026 Zviluppatur
F'din il-paġna
  1. Librerija ta’ utilità għall-awdjo
  2. PCM16 għal base64 u lura dawn
  3. Kampjunar mill-ġdid (Resampling)
  4. Konverżjoni bejn G.711 u PCM
  5. Detezzjoni tas-silenzju fuq in-naħa tal-klijent
  6. Ħażna u tagħbija ta’ fajls WAV
  7. Punti Ewlenin
  8. Iċċekkja l-fehim tiegħek

Librerija ta’ utilità għall-awdjo

Biex tibni applikazzjoni robusta ta’ Aġent Vokali, għandek bżonn funzjonijiet ta’ utilità li jikkonvertu l-awdjo bejn formati differenti. Din il-lezzjoni tiġbor l-għodod essenzjali ta’ Python għall-ipproċessar tal-awdjo f’ħin reali.

PCM16 għal base64 u lura dawn

Dawn huma ż-żewġ funzjonijiet li se tuża l-aktar: l-inkodjar tal-awdjo maqbud f’base64 biex tibgħatu, u d-dekodjar tal-awdjo base64 riċevut biex tdoqqu.

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

Kif tużahom fil-fluss tal-Aġent Vokali

import pyaudio
import json

# Qbid tal-mikrofon → ibgħat
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
    }))

# Irċievi → doqq
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())

Kampjunar mill-ġdid (Resampling)

Jekk il-mikrofon tiegħek jaqbad b’rata ta’ kampjunar differenti minn dik li tistenna l-API, għandek bżonn tagħmel resampling:

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)

# Eżempju: mikrofon f'44100 Hz → API f'24000 Hz
audio_44100 = capture_microphone()
audio_24000 = resample_audio(audio_44100, 44100, 24000)
b64 = audio_to_base64(audio_24000)

Konverżjoni bejn G.711 u PCM

Għall-integrazzjonijiet tat-telefon, ikollok bżonn tikkonverti bejn G.711 u PCM lineari. Oqgħod attent għall-verżjoni ta’ Python tiegħek: audioop tneħħa mil-librerija standard f’3.13. Fuq Python riċenti, installa l-pakkett audioop-lts, li jipprovdi l-istess interfaċċa:

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)

Relay sħiħ għat-telefon

Hawnhekk hemm eżempju ta’ relay bejn stream SIP G.711 u l-API tal-Aġent Vokali:

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:
        # Konverti 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)

Detezzjoni tas-silenzju fuq in-naħa tal-klijent

Jekk timmaniġġja int stess il-push-to-talk, jew trid detezzjoni lokali tas-silenzju qabel ma tibgħat, din il-funzjoni tkejjel l-enerġija tas-sinjal:

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

# Użu
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
    }))

Ħażna u tagħbija ta’ fajls WAV

Għad-debugging u t-testijiet, tista’ taħżen u ttella’ fajls 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

Punti Ewlenin

  • audio_to_base64 u base64_to_audio huma ż-żewġ funzjonijiet essenzjali għall-fluss tal-Aġent Vokali
  • Ir-resampling huwa meħtieġ meta r-rata ta’ kampjunar tal-mikrofon tiegħek ma taqbilx ma’ dik tal-API
  • Il-modulu audioop jimmaniġġja l-konverżjonijiet G.711 mu-law u A-law; tneħħa mil-librerija standard f’Python 3.13, allura installa audioop-lts minn PyPI fuq verżjonijiet riċenti
  • Id-detezzjoni tas-silenzju fuq in-naħa tal-klijent tiffranka bandwidth billi tibgħat biss awdjo utli
  • L-utilitajiet WAV jagħmlu d-debugging aktar faċli billi jħalluk taħżen u terġa’ tdoqq streams tal-awdjo

Iċċekkja l-fehim tiegħek

WebSocket, VAD, awdjo: l-aġent vokali minn tarf għal tarf.

1. Kif tissettja sessjoni ta' Aġent Vokali?

Tweġiba: B’konnessjoni WebSocket f’ħin reali, awtentikata b’tokens efimeri (qatt iċ-ċavetta prinċipali fuq il-klijent), imbagħad ikkonfigurata permezz ta’ session.update u kkonfermata minn session.created u session.updated.

2. X'jimmaniġġja l-VAD?

Tweġiba: Detezzjoni awtomatika tad-diskors: tiskopri meta l-utent jibda u jieqaf jitkellem, sabiex l-aġent ikun jaf meta jisma’ u meta jwieġeb, mingħajr l-ebda buttuna.

3. Kif jiċċirkola l-awdjo?

Tweġiba: L-input joħroġ permezz ta’ input_audio_buffer.append (b’buffer commit u clear), u r-risposta tasal bħala events tal-awdjo biex jindoqqu, f’PCM jew G.711 skont il-kanal.

4. X'jippermettu l-għodod u l-MCP f'konversazzjoni vokali?

Tweġiba: Sejħa ta’ funzjonijiet u għodod integrati (web, X, kollezzjonijiet) matul l-iskambju mitkellem: l-aġent ifittex affarijiet u jieħu azzjoni waqt li jitkellem, inklużi l-events tal-MCP.

5. U għat-telefonija?

Tweġiba: SIP u LiveKit ma’ G.711: l-aġent vokali jingħaqad man-netwerk tat-telefon, u l-utilitajiet ta’ konverżjoni tal-awdjo ta’ Python jgħaqqdu l-formati.

Sessjoni sigura, VAD, buffers immaniġġjati sew, għodod fil-vuċi: l-assistent sħiħ tat-telefon huwa fil-portata tiegħek, u dan il-kors tah kull biċċa meħtieġa.