refactor: build WAV containers with pcm_to_wav

The websocket transports, segmented STT, audio context messages, and the eval
recorder each hand-rolled the same wave boilerplate.

Author: markbackman

src/pipecat/evals/speech.py

@@ -27,7 +27,6 @@
 rate.
 """
 
-import asyncio
 import hashlib
 import importlib
 import os
@@ -38,6 +37,7 @@
 
 from loguru import logger
 
+from pipecat.audio.utils import pcm_to_wav
 from pipecat.evals.services import cartesia_service, kokoro_service
 from pipecat.services.tts_service import TTSService
 from pipecat.services.websocket_service import WebsocketService
@@ -350,8 +350,4 @@ def _read_wav(path: Path) -> tuple[bytes, int]:
     @staticmethod
     def _write_wav(path: Path, pcm: bytes, sample_rate: int) -> None:
         """Write mono 16-bit PCM to a WAV file."""
-        with wave.open(str(path), "wb") as wf:
-            wf.setnchannels(1)
-            wf.setsampwidth(2)
-            wf.setframerate(sample_rate)
-            wf.writeframes(pcm)
+        path.write_bytes(pcm_to_wav(pcm, sample_rate))

src/pipecat/evals/transport.py

@@ -45,7 +45,6 @@
 
 import asyncio
 import io
-import wave
 from collections.abc import Awaitable, Callable
 from pathlib import Path
 from urllib.parse import parse_qs, urlsplit
@@ -54,6 +53,7 @@
 from loguru import logger
 from PIL import Image
 
+from pipecat.audio.utils import pcm_to_wav
 from pipecat.frames.frames import (
     CancelFrame,
     EndFrame,
@@ -111,17 +111,12 @@ async def _write_wav(path: str, audio: bytes, sample_rate: int, num_channels: in
     Encodes the WAV in memory, then writes it to disk without blocking the event
     loop.
     """
-    buffer = io.BytesIO()
-    with wave.open(buffer, "wb") as wf:
-        wf.setnchannels(num_channels)
-        wf.setsampwidth(2)
-        wf.setframerate(sample_rate)
-        wf.writeframes(audio)
+    wav = pcm_to_wav(audio, sample_rate, num_channels)
 
     p = Path(path)
     p.parent.mkdir(parents=True, exist_ok=True)
     async with aiofiles.open(p, "wb") as f:
-        await f.write(buffer.getvalue())
+        await f.write(wav)
     logger.info(f"Eval recording saved: {p} ({len(audio)} bytes)")
 
 

src/pipecat/processors/aggregators/llm_context.py

@@ -18,7 +18,6 @@
 import base64
 import copy
 import io
-import wave
 from collections.abc import Callable
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any, Literal, TypeAlias, cast, overload
@@ -29,6 +28,7 @@
 from pipecat.adapters.schemas.direct_function import DirectFunction
 from pipecat.adapters.schemas.function_schema import FunctionSchema
 from pipecat.adapters.schemas.tools_schema import ToolsSchema
+from pipecat.audio.utils import pcm_to_wav
 from pipecat.frames.frames import AudioRawFrame
 
 # The sentinel is part of LLMContext's public surface — tools and tool_choice
@@ -191,15 +191,8 @@ def encode_audio():
 
             data = b"".join(frame.audio for frame in audio_frames)
 
-            with io.BytesIO() as buffer:
-                with wave.open(buffer, "wb") as wf:
-                    wf.setsampwidth(2)
-                    wf.setnchannels(num_channels)
-                    wf.setframerate(sample_rate)
-                    wf.writeframes(data)
-
-                encoded_audio = base64.b64encode(buffer.getvalue()).decode("utf-8")
-            return encoded_audio
+            wav = pcm_to_wav(data, sample_rate, num_channels)
+            return base64.b64encode(wav).decode("utf-8")
 
         encoded_audio = await asyncio.to_thread(encode_audio)
 

src/pipecat/services/stt_service.py

@@ -7,17 +7,16 @@
 """Base classes for Speech-to-Text services with continuous and segmented processing."""
 
 import asyncio
-import io
 import time
 import warnings
-import wave
 from abc import abstractmethod
 from collections.abc import AsyncGenerator
 from typing import Any
 
 from loguru import logger
 from websockets.protocol import State
 
+from pipecat.audio.utils import pcm_to_wav
 from pipecat.frames.frames import (
     AudioRawFrame,
     CancelFrame,
@@ -879,15 +878,7 @@ async def _handle_user_stopped_speaking(self, frame: VADUserStoppedSpeakingFrame
         await self.emit_stt_usage_metrics()
 
         if self.wants_wav_segments:
-            content = io.BytesIO()
-            wav = wave.open(content, "wb")
-            wav.setsampwidth(2)
-            wav.setnchannels(1)
-            wav.setframerate(self.sample_rate)
-            wav.writeframes(self._audio_buffer)
-            wav.close()
-            content.seek(0)
-            audio = content.read()
+            audio = pcm_to_wav(self._audio_buffer, self.sample_rate)
         else:
             # Local models read the buffer as raw 16-bit PCM; wrapping it in a
             # WAV container would make them misread the 44-byte header as audio.

src/pipecat/transports/websocket/client.py

@@ -12,16 +12,15 @@
 """
 
 import asyncio
-import io
 import time
-import wave
 from collections.abc import Awaitable, Callable
 
 import websockets
 from loguru import logger
 from pydantic.main import BaseModel
 from websockets.asyncio.client import connect as websocket_connect
 
+from pipecat.audio.utils import pcm_to_wav
 from pipecat.frames.frames import (
     CancelFrame,
     EndFrame,
@@ -436,18 +435,11 @@ async def write_audio_frame(self, frame: OutputAudioRawFrame) -> bool:
         )
 
         if self._params.add_wav_header:
-            with io.BytesIO() as buffer:
-                with wave.open(buffer, "wb") as wf:
-                    wf.setsampwidth(2)
-                    wf.setnchannels(frame.num_channels)
-                    wf.setframerate(frame.sample_rate)
-                    wf.writeframes(frame.audio)
-                wav_frame = OutputAudioRawFrame(
-                    buffer.getvalue(),
-                    sample_rate=frame.sample_rate,
-                    num_channels=frame.num_channels,
-                )
-                frame = wav_frame
+            frame = OutputAudioRawFrame(
+                pcm_to_wav(frame.audio, frame.sample_rate, frame.num_channels),
+                sample_rate=frame.sample_rate,
+                num_channels=frame.num_channels,
+            )
 
         await self._write_frame(frame)
 

src/pipecat/transports/websocket/fastapi.py

@@ -12,15 +12,14 @@
 """
 
 import asyncio
-import io
 import time
 import typing
-import wave
 from collections.abc import Awaitable, Callable
 
 from loguru import logger
 from pydantic import BaseModel, Field
 
+from pipecat.audio.utils import pcm_to_wav
 from pipecat.frames.frames import (
     CancelFrame,
     ClientConnectedFrame,
@@ -535,18 +534,11 @@ async def write_audio_frame(self, frame: OutputAudioRawFrame) -> bool:
         )
 
         if self._params.add_wav_header:
-            with io.BytesIO() as buffer:
-                with wave.open(buffer, "wb") as wf:
-                    wf.setsampwidth(2)
-                    wf.setnchannels(frame.num_channels)
-                    wf.setframerate(frame.sample_rate)
-                    wf.writeframes(frame.audio)
-                wav_frame = OutputAudioRawFrame(
-                    buffer.getvalue(),
-                    sample_rate=frame.sample_rate,
-                    num_channels=frame.num_channels,
-                )
-                frame = wav_frame
+            frame = OutputAudioRawFrame(
+                pcm_to_wav(frame.audio, frame.sample_rate, frame.num_channels),
+                sample_rate=frame.sample_rate,
+                num_channels=frame.num_channels,
+            )
 
         await self._write_frame(frame)
 

src/pipecat/transports/websocket/server.py

@@ -12,9 +12,7 @@
 """
 
 import asyncio
-import io
 import time
-import wave
 from collections.abc import Awaitable, Callable
 from typing import cast
 
@@ -25,6 +23,7 @@
 from websockets.protocol import State
 from websockets.typing import Origin
 
+from pipecat.audio.utils import pcm_to_wav
 from pipecat.frames.frames import (
     CancelFrame,
     ClientConnectedFrame,
@@ -460,18 +459,11 @@ async def write_audio_frame(self, frame: OutputAudioRawFrame) -> bool:
         )
 
         if self._params.add_wav_header:
-            with io.BytesIO() as buffer:
-                with wave.open(buffer, "wb") as wf:
-                    wf.setsampwidth(2)
-                    wf.setnchannels(frame.num_channels)
-                    wf.setframerate(frame.sample_rate)
-                    wf.writeframes(frame.audio)
-                wav_frame = OutputAudioRawFrame(
-                    buffer.getvalue(),
-                    sample_rate=frame.sample_rate,
-                    num_channels=frame.num_channels,
-                )
-                frame = wav_frame
+            frame = OutputAudioRawFrame(
+                pcm_to_wav(frame.audio, frame.sample_rate, frame.num_channels),
+                sample_rate=frame.sample_rate,
+                num_channels=frame.num_channels,
+            )
 
         await self._write_frame(frame)