openspeechapi 0.1.0__py3-none-any.whl

openspeech/utils/audio_converter.py

@@ -0,0 +1,406 @@
+"""Unified audio format conversion utilities for OpenSpeech.
+
+Centralises format detection, PCM/WAV/AIFF conversions (stdlib only) and
+MP3/OGG/FLAC/OPUS conversions (via ffmpeg subprocess).
+"""
+from __future__ import annotations
+
+import io
+import shutil
+import struct
+import subprocess
+import wave
+
+from openspeech.core.enums import AudioFormat
+from openspeech.core.models import AudioData
+
+
+class AudioConverter:
+    """Stateless audio conversion helper -- all public methods are static."""
+
+    # -- format detection -----------------------------------------------------
+
+    @staticmethod
+    def detect_format(data: bytes) -> AudioFormat:
+        """Detect audio format from file header magic bytes.
+
+        Falls back to ``AudioFormat.PCM_16K`` when the header is not
+        recognised (raw PCM has no header).
+        """
+        if len(data) >= 12 and data[:4] == b"RIFF" and data[8:12] == b"WAVE":
+            return AudioFormat.WAV
+        if len(data) >= 12 and data[:4] == b"FORM" and data[8:12] in (b"AIFF", b"AIFC"):
+            return AudioFormat.AIFF
+        if len(data) >= 4 and data[:4] == b"fLaC":
+            return AudioFormat.FLAC
+        if len(data) >= 4 and data[:4] == b"OggS":
+            return AudioFormat.OGG
+        # MP3: ID3 tag or MPEG frame sync
+        if len(data) >= 3 and data[:3] == b"ID3":
+            return AudioFormat.MP3
+        if len(data) >= 2 and data[0] == 0xFF and (data[1] & 0xE0) == 0xE0:
+            return AudioFormat.MP3
+        return AudioFormat.PCM_16K
+
+    # -- ffmpeg helpers -------------------------------------------------------
+
+    @staticmethod
+    def ffmpeg_available() -> bool:
+        """Return *True* if ffmpeg is found on ``$PATH``."""
+        return shutil.which("ffmpeg") is not None
+
+    @staticmethod
+    def _require_ffmpeg() -> None:
+        if not AudioConverter.ffmpeg_available():
+            raise RuntimeError(
+                "ffmpeg is required for this conversion but was not found on $PATH"
+            )
+
+    @staticmethod
+    def _ffmpeg_convert(
+        input_data: bytes,
+        input_format: str,
+        output_format: str,
+        sample_rate: int | None = None,
+        channels: int | None = None,
+    ) -> bytes:
+        """Run ffmpeg with stdin/stdout pipes (no temp files)."""
+        AudioConverter._require_ffmpeg()
+
+        cmd: list[str] = [
+            "ffmpeg",
+            "-y",
+            "-f", input_format,
+            "-i", "pipe:0",
+        ]
+        if sample_rate is not None:
+            cmd += ["-ar", str(sample_rate)]
+        if channels is not None:
+            cmd += ["-ac", str(channels)]
+        cmd += ["-f", output_format, "pipe:1"]
+
+        proc = subprocess.run(
+            cmd,
+            input=input_data,
+            capture_output=True,
+            check=False,
+        )
+        if proc.returncode != 0:
+            raise RuntimeError(f"ffmpeg failed: {proc.stderr.decode(errors='replace')}")
+        return proc.stdout
+
+    # -- PCM resampling -------------------------------------------------------
+
+    @staticmethod
+    def resample(pcm_data: bytes, src_rate: int, dst_rate: int) -> bytes:
+        """Resample 16-bit PCM using linear interpolation.
+
+        Returns the data unchanged when *src_rate* == *dst_rate*.
+        """
+        if src_rate == dst_rate:
+            return pcm_data
+
+        # Unpack 16-bit signed little-endian samples
+        n_samples = len(pcm_data) // 2
+        samples = struct.unpack(f"<{n_samples}h", pcm_data)
+
+        ratio = src_rate / dst_rate
+        out_len = int(n_samples / ratio)
+        out: list[int] = []
+        for i in range(out_len):
+            src_pos = i * ratio
+            idx = int(src_pos)
+            frac = src_pos - idx
+            if idx + 1 < n_samples:
+                val = samples[idx] * (1 - frac) + samples[idx + 1] * frac
+            else:
+                val = samples[idx] if idx < n_samples else 0
+            # Clamp to int16 range
+            val = max(-32768, min(32767, int(round(val))))
+            out.append(val)
+
+        return struct.pack(f"<{len(out)}h", *out)
+
+    # -- channel mixing -------------------------------------------------------
+
+    @staticmethod
+    def mix_to_mono(pcm_data: bytes, channels: int) -> bytes:
+        """Mix multi-channel 16-bit PCM down to mono by averaging channels."""
+        if channels <= 1:
+            return pcm_data
+
+        n_samples = len(pcm_data) // 2
+        samples = struct.unpack(f"<{n_samples}h", pcm_data)
+
+        frames = n_samples // channels
+        out: list[int] = []
+        for f in range(frames):
+            total = 0
+            for c in range(channels):
+                total += samples[f * channels + c]
+            avg = total // channels
+            avg = max(-32768, min(32767, avg))
+            out.append(avg)
+
+        return struct.pack(f"<{len(out)}h", *out)
+
+    # -- AIFF support ---------------------------------------------------------
+
+    @staticmethod
+    def _parse_aiff_extended(data: bytes) -> float:
+        """Parse an 80-bit IEEE 754 extended precision float (big-endian).
+
+        Used by AIFF to encode the sample rate in the COMM chunk.
+        """
+        # 80-bit extended: 1 sign, 15 exponent, 64 mantissa
+        exponent = ((data[0] & 0x7F) << 8) | data[1]
+        mantissa = 0
+        for i in range(2, 10):
+            mantissa = (mantissa << 8) | data[i]
+        sign = -1 if data[0] & 0x80 else 1
+        if exponent == 0 and mantissa == 0:
+            return 0.0
+        exponent -= 16383  # bias
+        # mantissa has explicit integer bit
+        value = sign * (mantissa / (1 << 63)) * (2 ** exponent)
+        return value
+
+    @staticmethod
+    def _aiff_to_pcm(data: bytes) -> tuple[bytes, int, int]:
+        """Read AIFF data and return (pcm_le_bytes, sample_rate, channels).
+
+        AIFF stores samples as big-endian; this converts to little-endian
+        16-bit PCM.  Parses AIFF manually to avoid the removed ``aifc``
+        module (dropped in Python 3.13).
+        """
+        if len(data) < 12 or data[:4] != b"FORM" or data[8:12] not in (b"AIFF", b"AIFC"):
+            raise RuntimeError("Not a valid AIFF file")
+
+        is_aifc = data[8:12] == b"AIFC"
+        n_channels = 0
+        samp_width = 0
+        frame_rate = 0
+        n_frames = 0
+        raw = b""
+        compression_type = b"NONE"
+
+        pos = 12
+        while pos < len(data) - 8:
+            chunk_id = data[pos : pos + 4]
+            chunk_size = struct.unpack(">I", data[pos + 4 : pos + 8])[0]
+            chunk_data = data[pos + 8 : pos + 8 + chunk_size]
+
+            if chunk_id == b"COMM":
+                # COMM: channels(2), numFrames(4), sampleSize(2), sampleRate(10 extended)
+                n_channels = struct.unpack(">h", chunk_data[0:2])[0]
+                n_frames = struct.unpack(">I", chunk_data[2:6])[0]
+                samp_width = struct.unpack(">h", chunk_data[6:8])[0] // 8
+                frame_rate = int(AudioConverter._parse_aiff_extended(chunk_data[8:18]))
+                # AIFF-C has compression type after the 18-byte standard COMM fields
+                if is_aifc and len(chunk_data) >= 22:
+                    compression_type = chunk_data[18:22]
+            elif chunk_id == b"SSND":
+                # SSND: offset(4), blockSize(4), then raw sample data
+                offset = struct.unpack(">I", chunk_data[0:4])[0]
+                raw = chunk_data[8 + offset :]
+
+            # Skip FVER and other AIFC-specific chunks
+            # Chunks are padded to even size
+            pos += 8 + chunk_size + (chunk_size % 2)
+
+        if n_channels == 0:
+            raise RuntimeError("AIFF file missing COMM chunk")
+
+        # AIFF-C compression: NONE and twos are big-endian PCM (standard),
+        # sowt is little-endian PCM (no byte swap needed)
+        if is_aifc and compression_type not in (b"NONE", b"twos", b"sowt"):
+            raise RuntimeError(
+                f"Unsupported AIFF-C compression: {compression_type!r}. "
+                "Only uncompressed AIFF/AIFF-C is supported."
+            )
+
+        is_little_endian = is_aifc and compression_type == b"sowt"
+
+        # Convert samples to little-endian 16-bit PCM
+        if samp_width == 2:
+            n = len(raw) // 2
+            if is_little_endian:
+                pcm = raw[:n * 2]
+            else:
+                be_samples = struct.unpack(f">{n}h", raw)
+                pcm = struct.pack(f"<{n}h", *be_samples)
+        elif samp_width == 1:
+            pcm = b"".join(
+                struct.pack("<h", (b - 128) * 256) for b in raw
+            )
+        else:
+            raise RuntimeError(f"Unsupported AIFF sample width: {samp_width * 8}-bit")
+
+        return pcm, frame_rate, n_channels
+
+    # -- core conversions -----------------------------------------------------
+
+    @staticmethod
+    def to_wav(
+        audio: AudioData,
+        target_rate: int | None = None,
+        target_channels: int | None = None,
+    ) -> AudioData:
+        """Convert *audio* to WAV format.
+
+        Optionally resample and/or remix channels.  WAV input is returned
+        unchanged unless resampling/remixing is requested.
+        """
+        fmt = audio.format
+
+        # Obtain raw PCM + metadata
+        if fmt == AudioFormat.WAV:
+            # Decode existing WAV to get raw PCM
+            with wave.open(io.BytesIO(audio.data), "rb") as wf:
+                pcm = wf.readframes(wf.getnframes())
+                rate = wf.getframerate()
+                ch = wf.getnchannels()
+        elif fmt == AudioFormat.AIFF:
+            pcm, rate, ch = AudioConverter._aiff_to_pcm(audio.data)
+        elif fmt in (AudioFormat.PCM_16K, AudioFormat.PCM_44K):
+            pcm = audio.data
+            rate = audio.sample_rate
+            ch = audio.channels
+        elif fmt in (AudioFormat.MP3, AudioFormat.OGG, AudioFormat.FLAC, AudioFormat.OPUS):
+            # Use ffmpeg to decode to raw PCM first
+            fmt_map = {
+                AudioFormat.MP3: "mp3",
+                AudioFormat.OGG: "ogg",
+                AudioFormat.FLAC: "flac",
+                AudioFormat.OPUS: "ogg",
+            }
+            raw = AudioConverter._ffmpeg_convert(
+                audio.data, fmt_map[fmt], "s16le",
+                sample_rate=target_rate or audio.sample_rate,
+                channels=target_channels or audio.channels,
+            )
+            out_rate = target_rate or audio.sample_rate
+            out_ch = target_channels or audio.channels
+            buf = io.BytesIO()
+            with wave.open(buf, "wb") as wf:
+                wf.setnchannels(out_ch)
+                wf.setsampwidth(2)
+                wf.setframerate(out_rate)
+                wf.writeframes(raw)
+            return AudioData(
+                data=buf.getvalue(),
+                sample_rate=out_rate,
+                channels=out_ch,
+                format=AudioFormat.WAV,
+            )
+        else:
+            raise RuntimeError(f"Unsupported format for to_wav: {fmt}")
+
+        # Optional channel remix
+        out_ch = target_channels or ch
+        if out_ch != ch:
+            if out_ch == 1:
+                pcm = AudioConverter.mix_to_mono(pcm, ch)
+            else:
+                raise RuntimeError("Only mono down-mix is supported")
+
+        # Optional resample
+        out_rate = target_rate or rate
+        if out_rate != rate:
+            # If multi-channel, must be mono at this point for simple resample
+            if out_ch > 1:
+                raise RuntimeError("Resample only supported for mono audio")
+            pcm = AudioConverter.resample(pcm, rate, out_rate)
+
+        # Wrap as WAV
+        buf = io.BytesIO()
+        with wave.open(buf, "wb") as wf:
+            wf.setnchannels(out_ch)
+            wf.setsampwidth(2)
+            wf.setframerate(out_rate)
+            wf.writeframes(pcm)
+
+        return AudioData(
+            data=buf.getvalue(),
+            sample_rate=out_rate,
+            channels=out_ch,
+            format=AudioFormat.WAV,
+        )
+
+    @staticmethod
+    def to_pcm16k(audio: AudioData) -> AudioData:
+        """Convert *audio* to 16 kHz mono 16-bit PCM."""
+        if (
+            audio.format == AudioFormat.PCM_16K
+            and audio.sample_rate == 16000
+            and audio.channels == 1
+        ):
+            return audio
+
+        # Go through WAV first, then extract raw PCM
+        wav = AudioConverter.to_wav(audio, target_rate=16000, target_channels=1)
+        with wave.open(io.BytesIO(wav.data), "rb") as wf:
+            pcm = wf.readframes(wf.getnframes())
+
+        return AudioData(
+            data=pcm,
+            sample_rate=16000,
+            channels=1,
+            format=AudioFormat.PCM_16K,
+        )
+
+    @staticmethod
+    def convert(audio: AudioData, target: AudioFormat) -> AudioData:
+        """Convert *audio* to *target* format."""
+        if audio.format == target:
+            return audio
+
+        # Targets achievable with stdlib
+        if target == AudioFormat.WAV:
+            return AudioConverter.to_wav(audio)
+        if target == AudioFormat.PCM_16K:
+            return AudioConverter.to_pcm16k(audio)
+        if target == AudioFormat.PCM_44K:
+            wav = AudioConverter.to_wav(audio, target_rate=44100)
+            with wave.open(io.BytesIO(wav.data), "rb") as wf:
+                pcm = wf.readframes(wf.getnframes())
+            return AudioData(
+                data=pcm,
+                sample_rate=44100,
+                channels=wav.channels,
+                format=AudioFormat.PCM_44K,
+            )
+
+        # Targets requiring ffmpeg
+        fmt_map = {
+            AudioFormat.MP3: "mp3",
+            AudioFormat.OGG: "ogg",
+            AudioFormat.FLAC: "flac",
+            AudioFormat.OPUS: "opus",
+        }
+        if target not in fmt_map:
+            raise RuntimeError(f"Unsupported target format: {target}")
+
+        # First ensure we have WAV (ffmpeg reads WAV easily)
+        wav = AudioConverter.to_wav(audio)
+        out = AudioConverter._ffmpeg_convert(
+            wav.data, "wav", fmt_map[target],
+            sample_rate=audio.sample_rate,
+            channels=audio.channels,
+        )
+        return AudioData(
+            data=out,
+            sample_rate=audio.sample_rate,
+            channels=audio.channels,
+            format=target,
+        )
+
+    # -- streaming (reserved) -------------------------------------------------
+
+    @staticmethod
+    def convert_stream(
+        audio: AudioData,
+        target: AudioFormat,
+    ) -> AudioData:
+        """Streaming conversion -- not yet implemented."""
+        raise NotImplementedError("Streaming conversion is not yet supported")

openspeech/utils/audio_playback.py

@@ -0,0 +1,156 @@
+"""Audio playback utilities for demo and external applications."""
+from __future__ import annotations
+
+import io
+import shutil
+import subprocess
+import tempfile
+import wave
+from array import array
+from pathlib import Path
+from typing import Any
+
+from openspeech.core.enums import AudioFormat
+from openspeech.core.models import AudioData
+
+
+def _wav_bytes_from_audio(audio: AudioData) -> bytes:
+    if audio.format == AudioFormat.WAV and audio.data[:4] == b"RIFF":
+        return audio.data
+
+    data = audio.data
+    if audio.format == AudioFormat.PCM_44K:
+        sample_rate = 44100
+    elif audio.format == AudioFormat.PCM_16K:
+        sample_rate = 16000
+    else:
+        sample_rate = audio.sample_rate
+
+    buf = io.BytesIO()
+    with wave.open(buf, "wb") as wf:
+        wf.setnchannels(audio.channels)
+        wf.setsampwidth(2)  # 16-bit PCM
+        wf.setframerate(sample_rate)
+        wf.writeframes(data)
+    return buf.getvalue()
+
+
+def _scale_pcm16(pcm_bytes: bytes, volume: float) -> bytes:
+    if volume == 1.0:
+        return pcm_bytes
+    samples = array("h")
+    samples.frombytes(pcm_bytes)
+    for i, s in enumerate(samples):
+        v = int(s * volume)
+        if v > 32767:
+            v = 32767
+        elif v < -32768:
+            v = -32768
+        samples[i] = v
+    return samples.tobytes()
+
+
+def _play_with_sounddevice(
+    audio: AudioData,
+    device: str | int | None,
+    volume: float,
+    blocking: bool,
+) -> None:
+    try:
+        import numpy as np
+        import sounddevice as sd
+    except ImportError as exc:
+        raise RuntimeError(
+            "sounddevice backend unavailable. Install extras: pip install openspeech[audio]"
+        ) from exc
+
+    wav_bytes = _wav_bytes_from_audio(audio)
+    with wave.open(io.BytesIO(wav_bytes), "rb") as wf:
+        frames = wf.readframes(wf.getnframes())
+        channels = wf.getnchannels()
+        sample_rate = wf.getframerate()
+        sample_width = wf.getsampwidth()
+
+    if sample_width != 2:
+        raise RuntimeError(f"Only 16-bit PCM playback is supported, got sample_width={sample_width}")
+
+    scaled = _scale_pcm16(frames, volume)
+    pcm = np.frombuffer(scaled, dtype=np.int16)
+    if channels > 1:
+        pcm = pcm.reshape(-1, channels)
+
+    sd.play(pcm, samplerate=sample_rate, device=device, blocking=blocking)
+    if blocking:
+        sd.wait()
+
+
+def _play_with_external_player(
+    audio: AudioData,
+    device: str | int | None,
+    blocking: bool,
+) -> None:
+    if device is not None:
+        raise RuntimeError("device selection is only supported with backend='sounddevice'")
+
+    wav_bytes = _wav_bytes_from_audio(audio)
+    with tempfile.NamedTemporaryFile(prefix="openspeech_", suffix=".wav", delete=False) as f:
+        temp_path = Path(f.name)
+        f.write(wav_bytes)
+
+    if shutil.which("ffplay"):
+        cmd = ["ffplay", "-nodisp", "-autoexit", "-loglevel", "error", str(temp_path)]
+    elif shutil.which("afplay"):
+        cmd = ["afplay", str(temp_path)]
+    elif shutil.which("aplay"):
+        cmd = ["aplay", str(temp_path)]
+    else:
+        temp_path.unlink(missing_ok=True)
+        raise RuntimeError(
+            "No playback backend found. Install sounddevice or ffplay/afplay/aplay."
+        )
+
+    if blocking:
+        subprocess.run(cmd, check=False)
+        temp_path.unlink(missing_ok=True)
+    else:
+        subprocess.Popen(cmd)  # noqa: S603
+
+
+def play_audio(
+    audio: AudioData,
+    *,
+    device: str | int | None = None,
+    volume: float = 1.0,
+    blocking: bool = True,
+    backend: str = "auto",
+) -> None:
+    """Play AudioData with optional backend/device selection."""
+    if volume <= 0:
+        raise ValueError("volume must be > 0")
+    backend = backend.lower().strip()
+    if backend not in {"auto", "sounddevice", "external"}:
+        raise ValueError("backend must be one of: auto, sounddevice, external")
+
+    if backend in {"auto", "sounddevice"}:
+        try:
+            _play_with_sounddevice(audio, device=device, volume=volume, blocking=blocking)
+            return
+        except RuntimeError:
+            if backend == "sounddevice":
+                raise
+
+    _play_with_external_player(audio, device=device, blocking=blocking)
+
+
+def list_output_devices() -> list[dict[str, Any]]:
+    """List playback devices for sounddevice backend."""
+    try:
+        import sounddevice as sd
+    except ImportError:
+        return []
+
+    devices = []
+    for idx, dev in enumerate(sd.query_devices()):  # type: ignore[arg-type]
+        if dev.get("max_output_channels", 0) > 0:
+            devices.append({"id": idx, "name": dev.get("name", f"device-{idx}")})
+    return devices

openspeech/vendor_registry.yaml

@@ -0,0 +1,74 @@
+# Vendor Registry — cloud provider service templates.
+# Defines shared credential fields for each vendor.
+# Engines reference vendors via the "vendor" field in engine_registry.yaml.
+version: 1
+
+vendors:
+  openai:
+    display_name: "OpenAI"
+    shared_fields:
+      api_key: { required: true, description: "API Key", secret: true }
+      base_url: { required: false, description: "API Base URL (leave empty for default)", default: "" }
+
+  iflytek:
+    display_name: "iFlytek (科大讯飞)"
+    shared_fields:
+      app_id: { required: true, description: "App ID" }
+      api_key: { required: true, description: "API Key", secret: true }
+      api_secret: { required: true, description: "API Secret", secret: true }
+
+  google:
+    display_name: "Google Cloud"
+    shared_fields:
+      api_key: { required: true, description: "API Key", secret: true }
+
+  azure:
+    display_name: "Azure"
+    shared_fields:
+      subscription_key: { required: true, description: "Subscription Key", secret: true }
+      region: { required: true, description: "Region", default: "eastus" }
+
+  alibaba:
+    display_name: "Alibaba (阿里云)"
+    shared_fields:
+      api_key: { required: true, description: "API Key", secret: true }
+      base_url: { required: false, description: "API Base URL", default: "https://dashscope.aliyuncs.com/compatible-mode/v1" }
+
+  tencent:
+    display_name: "Tencent (腾讯云)"
+    shared_fields:
+      secret_id: { required: true, description: "Secret ID", secret: true }
+      secret_key: { required: true, description: "Secret Key", secret: true }
+
+  baidu:
+    display_name: "Baidu (百度)"
+    shared_fields:
+      api_key: { required: true, description: "API Key", secret: true }
+      secret_key: { required: true, description: "Secret Key", secret: true }
+
+  volcengine:
+    display_name: "Volcengine (火山引擎)"
+    shared_fields:
+      access_token: { required: true, description: "Access Token", secret: true }
+      app_id: { required: true, description: "App ID" }
+
+  deepgram:
+    display_name: "Deepgram"
+    shared_fields:
+      api_key: { required: true, description: "API Key", secret: true }
+
+  assemblyai:
+    display_name: "AssemblyAI"
+    shared_fields:
+      api_key: { required: true, description: "API Key", secret: true }
+
+  elevenlabs:
+    display_name: "ElevenLabs"
+    shared_fields:
+      api_key: { required: true, description: "API Key", secret: true }
+
+  minimax:
+    display_name: "MiniMax"
+    shared_fields:
+      api_key: { required: true, description: "API Key", secret: true }
+      group_id: { required: true, description: "Group ID" }