simulstream 0.1.0__py3-none-any.whl

docs/source/conf.py

@@ -0,0 +1,47 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath('../../'))
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'simulstream'
+copyright = '2025, FBK'
+author = 'Marco Gaido, FBK MT Unit'
+release = '0.1.0'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    'sphinx.ext.duration',
+    'sphinx.ext.doctest',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.intersphinx',
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+]
+
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3/', None),
+    'sphinx': ('https://www.sphinx-doc.org/en/master/', None),
+}
+intersphinx_disabled_domains = ['std']
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_logo = "_static/logo.png"
+html_favicon = "_static/logo.png"
+html_css_files = ['custom.css']
+
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']

simulstream/__init__.py

@@ -0,0 +1,15 @@
+# Copyright 2025 FBK
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License
+
+__version__ = '0.1.0'

simulstream/client/wav_reader_client.py

@@ -0,0 +1,228 @@
+# Copyright 2025 FBK
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License
+
+import argparse
+import asyncio
+import json
+import logging
+import wave
+from typing import Tuple, Optional, List
+
+import numpy as np
+import websockets
+import os
+import contextlib
+
+
+logging.basicConfig(
+    format='%(asctime)s | %(levelname)s | %(name)s | %(message)s',
+    datefmt='%Y-%m-%d %H:%M:%S',
+    level=logging.INFO,
+)
+LOGGER = logging.getLogger('simulstream.wav_reader_client')
+
+
+def float32_to_int16(audio_data: np.ndarray) -> np.ndarray:
+    """Convert a NumPy array of float32 audio samples to int16 PCM format."""
+    audio_data = np.clip(audio_data * 2 ** 15, -32768, 32767)
+    return audio_data.astype(np.int16)
+
+
+def read_wav_file(filename: str) -> Tuple[int, np.ndarray]:
+    """
+    Read a WAV file and return its sample rate and audio data.
+
+    Args:
+        filename (str): Path to the WAV file.
+
+    Returns:
+        tuple[int, np.ndarray]: Sample rate and mono audio data as int16 array.
+
+    Raises:
+        ValueError: If the sample width is unsupported.
+        AssertionError: If the file contains more than one channel.
+    """
+    with contextlib.closing(wave.open(filename, 'rb')) as wf:
+        num_channels = wf.getnchannels()
+        sample_width = wf.getsampwidth()
+        sample_rate = wf.getframerate()
+        num_frames = wf.getnframes()
+        raw_data = wf.readframes(num_frames)
+
+        if sample_width == 2:
+            dtype = np.int16
+        elif sample_width == 4:
+            dtype = np.float32
+        else:
+            raise ValueError(f"Unsupported sample width: {sample_width}")
+
+        data = np.frombuffer(raw_data, dtype=dtype)
+
+        if sample_width == 4:
+            data = float32_to_int16(data)
+
+        assert num_channels == 1, "Currently ony 1 channel is supported"
+
+        return sample_rate, data
+
+
+async def send_audio(
+        websocket: websockets.ClientConnection,
+        sample_rate: int,
+        data: np.ndarray,
+        chunk_duration_ms: int = 100):
+    """
+    Stream audio data in fixed-size chunks over a WebSocket connection.
+
+    Args:
+        websocket (websockets.ClientConnection): Active WebSocket connection.
+        sample_rate (int): Audio sample rate (Hz).
+        data (np.ndarray): Audio samples as int16 array.
+        chunk_duration_ms (int): Duration of each chunk in milliseconds.
+    """
+    samples_per_chunk = int(sample_rate * chunk_duration_ms / 1000.0)
+    i = 0
+    for i in range(0, len(data), samples_per_chunk):
+        await websocket.send(data[i:i + samples_per_chunk].tobytes())
+    # send last part of the audio
+    if i < len(data):
+        await websocket.send(data[i:].tobytes())
+
+
+async def stream_wav_files(
+        uri: str,
+        wav_file_list: List[str],
+        chunk_duration_ms: int = 100,
+        tgt_lang: Optional[str] = None,
+        src_lang: Optional[str] = None):
+    """
+    Stream multiple WAV files sequentially to a WebSocket server.
+
+    For each file:
+      - Sends metadata (sample rate, filename, optional languages).
+      - Streams audio in chunks.
+      - Sends an end-of-stream marker.
+      - Waits for server confirmation before proceeding.
+
+    Args:
+        uri (str): WebSocket server URI.
+        wav_file_list (list[str]): Paths to WAV files.
+        chunk_duration_ms (int): Chunk size in milliseconds.
+        tgt_lang (str | None): Target language code (e.g., "en").
+        src_lang (str | None): Source language code (e.g., "en").
+    """
+    for wav_file in wav_file_list:
+        LOGGER.info(f"Streaming: {wav_file}")
+        sample_rate, data = read_wav_file(wav_file)
+        metadata = {
+            "sample_rate": sample_rate,
+            "metrics_metadata": {
+                "wav_name": wav_file,
+            }
+        }
+        if tgt_lang is not None:
+            metadata["target_lang"] = tgt_lang
+        if src_lang is not None:
+            metadata["source_lang"] = src_lang
+        async with websockets.connect(uri, ping_timeout=None) as websocket:
+            await websocket.send(json.dumps(metadata))
+            await send_audio(websocket, sample_rate, data, chunk_duration_ms)
+            await websocket.send(json.dumps({"end_of_stream": True}))
+            while True:
+                response = await websocket.recv()
+                LOGGER.debug(response)
+                if 'end_of_processing' in response:
+                    break
+    LOGGER.info(f"All {len(wav_file_list)} files sent.")
+
+
+def load_wav_file_list(list_file_path: str) -> List[str]:
+    """
+    Load a list of WAV file paths from a text file.
+
+    Args:
+        list_file_path (str): Path to a text file, one WAV file path per line.
+
+    Returns:
+        list[str]: Absolute file paths of WAV files.
+    """
+    basedir = os.path.dirname(list_file_path)
+    with open(list_file_path, 'r') as f:
+        wav_files = [basedir + '/' + line.strip() for line in f if line.strip()]
+    if not wav_files:
+        LOGGER.error("No valid WAV files found in the list.")
+        exit(1)
+    else:
+        assert all(os.path.isfile(f) for f in wav_files), "Invalid wav file in the list."
+    return wav_files
+
+
+async def main(args: argparse.Namespace):
+    """Main entrypoint: validates WAV files and starts streaming."""
+    wav_files = load_wav_file_list(args.wav_list_file)
+    await stream_wav_files(
+        args.uri, wav_files, args.chunk_duration_ms, args.tgt_lang, args.src_lang)
+
+
+def cli_main():
+    """
+    Simulstream WebSocket client command-line interface (CLI) entry point.
+
+    This script implements a simple WebSocket client that streams audio data from a list of WAV
+    files to a server for processing (e.g., speech recognition or translation). It reads WAV files,
+    converts them into fixed-size chunks, and sends them asynchronously over a WebSocket
+    connection.
+
+    Example usage::
+
+        $ python wav_reader_client.py --uri ws://localhost:8000/ --wav-list-file wav_files.txt \\
+              --tgt-lang it --src-lang en
+
+    Command-line arguments:
+
+    - ``--uri``: WebSocket server URI (e.g., ``ws://localhost:8000/``).
+    - ``--wav-list-file``: Path to a text file containing one WAV file path per line.
+    - ``--chunk-duration-ms``: Duration of each audio chunk sent to the server (ms). Default: 100.
+    - ``--tgt-lang``: Optional target language.
+    - ``--src-lang``: Optional source language.
+    """
+    parser = argparse.ArgumentParser(description="Websocket client for WAV files.")
+    parser.add_argument(
+        "--uri",
+        required=True,
+        help="WebSocket server URI (e.g., ws://localhost:8000/)")
+    parser.add_argument(
+        "--wav-list-file",
+        required=True,
+        help="Path to text file containing list of WAV file paths")
+    parser.add_argument(
+        "--chunk-duration-ms",
+        default=100,
+        type=int,
+        help="Size of the each chunk sent to the server in milliseconds (default: 100)")
+    parser.add_argument(
+        "--tgt-lang",
+        default=None,
+        help="Target language (if needed, its effect depends on the speech processor used by the "
+             "server).")
+    parser.add_argument(
+        "--src-lang",
+        default=None,
+        help="Source language (if needed, its effect depends on the speech processor used by the "
+             "server).")
+    asyncio.run(main(parser.parse_args()))
+
+
+if __name__ == "__main__":
+    cli_main()

simulstream/config.py

@@ -0,0 +1,31 @@
+# Copyright 2025 FBK
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License
+
+from types import SimpleNamespace
+
+import yaml
+
+
+def _dict_to_object(d):
+    if isinstance(d, dict):
+        return SimpleNamespace(**{k: _dict_to_object(v) for k, v in d.items()})
+    elif isinstance(d, list):
+        return [_dict_to_object(i) for i in d]
+    else:
+        return d
+
+
+def yaml_config(path: str) -> SimpleNamespace:
+    with open(path, "r") as file:
+        return _dict_to_object(yaml.safe_load(file))

simulstream/inference.py

@@ -0,0 +1,170 @@
+# Copyright 2025 FBK
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License
+
+import argparse
+import json
+import logging
+import time
+from types import SimpleNamespace
+from typing import List, Optional
+
+import numpy as np
+
+import simulstream
+from simulstream.client.wav_reader_client import load_wav_file_list, read_wav_file
+from simulstream.config import yaml_config
+from simulstream.metrics.logger import setup_metrics_logger, METRICS_LOGGER
+from simulstream.server.message_processor import MessageProcessor
+from simulstream.server.speech_processors import build_speech_processor, SpeechProcessor
+
+
+logging.basicConfig(
+    format='%(asctime)s | %(levelname)s | %(name)s | %(message)s',
+    datefmt='%Y-%m-%d %H:%M:%S',
+    level=logging.INFO,
+)
+LOGGER = logging.getLogger('simulstream.inference')
+
+
+def process_audio(
+        message_processor: MessageProcessor,
+        sample_rate: int,
+        data: np.ndarray):
+    """
+    Stream audio data in fixed-size chunks over a WebSocket connection.
+
+    Args:
+        message_processor (MessageProcessor): class that processes the audio chunks.
+        sample_rate (int): Audio sample rate (Hz).
+        data (np.ndarray): Audio samples as int16 array.
+    """
+    samples_per_chunk = int(
+        sample_rate * message_processor.speech_processor.speech_chunk_size / 1000.0)
+    i = 0
+    for i in range(0, len(data), samples_per_chunk):
+        output = message_processor.process_speech(data[i:i + samples_per_chunk].tobytes())
+        LOGGER.debug(f"response: {output}")
+    # send last part of the audio
+    if i < len(data):
+        output = message_processor.process_speech(data[i:].tobytes())
+        LOGGER.debug(f"response: {output}")
+
+
+def run_inference(
+        speech_processor: SpeechProcessor,
+        wav_file_list: List[str],
+        tgt_lang: Optional[str] = None,
+        src_lang: Optional[str] = None):
+    """
+    Runs the inference on the WAV files sequentially with the specified speech processor.
+
+    For each file:
+      - Sets metadata (sample rate, filename, optional languages).
+      - Processes the audio in chunks.
+
+    Args:
+        speech_processor (SpeechProcessor): the speech processor to use to run the inference.
+        wav_file_list (list[str]): Paths to WAV files.
+        tgt_lang (str | None): Target language code (e.g., "en").
+        src_lang (str | None): Source language code (e.g., "en").
+    """
+    for i, wav_file in enumerate(wav_file_list):
+        LOGGER.info(f"Streaming: {wav_file}")
+        sample_rate, data = read_wav_file(wav_file)
+        metadata = {
+            "sample_rate": sample_rate,
+            "metrics_metadata": {
+                "wav_name": wav_file,
+            }
+        }
+        if tgt_lang is not None:
+            metadata["target_lang"] = tgt_lang
+        if src_lang is not None:
+            metadata["source_lang"] = src_lang
+        message_processor = MessageProcessor(i, speech_processor)
+        message_processor.process_metadata(metadata)
+        process_audio(message_processor, sample_rate, data)
+        message_processor.end_of_stream()
+    LOGGER.info(f"All {len(wav_file_list)} files sent.")
+
+
+def main(args: argparse.Namespace):
+    """
+    Main entrypoint: validates WAV files and starts the generation with the specified speech
+    processor.
+    """
+    setup_metrics_logger(SimpleNamespace(**{
+        "enabled": True,
+        "filename": args.metrics_log_file
+    }))
+    LOGGER.info(f"Loading speech processor from {args.speech_processor_config}")
+    speech_processor_config = yaml_config(args.speech_processor_config)
+    LOGGER.info(f"Using as speech processor: {speech_processor_config.type}")
+    speech_processor_loading_time = time.time()
+    speech_processor = build_speech_processor(speech_processor_config)
+    speech_processor_loading_time = time.time() - speech_processor_loading_time
+    LOGGER.info(f"Loaded speech processor in {speech_processor_loading_time:.3f} seconds")
+    METRICS_LOGGER.info(json.dumps({
+        "model_loading_time": speech_processor_loading_time,
+    }))
+    wav_files = load_wav_file_list(args.wav_list_file)
+    run_inference(speech_processor, wav_files, args.tgt_lang, args.src_lang)
+
+
+def cli_main():
+    """
+    Simulstream evaluation command-line interface (CLI) entry point. This script processes the
+    specified wav files with the configured speech processor and can be used to get the metrics
+    log file to evaluate the quality and latency of the speech processor.
+
+    This function parses command-line arguments and starts the asynchronous :func:`main` routine.
+
+    Example usage::
+
+        $ python inference.py --speech-processor-config config/speech.yaml \\
+              --wav-list-file wav_files.txt --tgt-lang it --src-lang en
+
+    Command-line arguments:
+
+    - ``--server-config`` (str, optional): Path to the server configuration file
+      (default: ``config/server.yaml``).
+    - ``--speech-processor-config`` (str, required): Path to the speech processor configuration
+      file.
+    """
+    LOGGER.info(f"Simulstream version: {simulstream.__version__}")
+    parser = argparse.ArgumentParser("simulstream_inference")
+    parser.add_argument("--speech-processor-config", type=str, required=True)
+    parser.add_argument(
+        "--wav-list-file",
+        required=True,
+        help="Path to text file containing list of WAV file paths")
+    parser.add_argument(
+        "--tgt-lang",
+        default=None,
+        help="Target language (if needed, its effect depends on the speech processor used by the "
+             "server).")
+    parser.add_argument(
+        "--src-lang",
+        default=None,
+        help="Source language (if needed, its effect depends on the speech processor used by the "
+             "server).")
+    parser.add_argument(
+        "--metrics-log-file",
+        default="metrics.json",
+        help="Path where to write the metrics log file.")
+    main(parser.parse_args())
+
+
+if __name__ == "__main__":
+    cli_main()

simulstream/metrics/detokenizers.py

@@ -0,0 +1,71 @@
+# Copyright 2025 FBK
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License
+
+from types import SimpleNamespace
+from typing import Callable, Dict, List
+
+
+def build_hf_detokenizer(config: SimpleNamespace) -> Callable[[List[str]], str]:
+    from transformers import AutoProcessor
+
+    assert hasattr(config, "hf_model_name"), \
+        "`hf_model_name` required in the eval config for `hf` detokenizer"
+    processor = AutoProcessor.from_pretrained(config.hf_model_name)
+
+    def detokenize(input_tokens: List[str]) -> str:
+        return processor.tokenizer.convert_tokens_to_string(input_tokens)
+
+    return detokenize
+
+
+def build_canary_detokenizer(config: SimpleNamespace) -> Callable[[List[str]], str]:
+    from nemo.collections.asr.models import ASRModel
+
+    assert hasattr(config, "model_name"), \
+        "`model_name` required in the eval config for `canary` detokenizer"
+    tokenizer = ASRModel.from_pretrained(model_name=config.model_name).tokenizer
+
+    def detokenize(input_tokens: List[str]) -> str:
+        return tokenizer.tokens_to_text(input_tokens)
+
+    return detokenize
+
+
+def build_simuleval_detokenizer(config: SimpleNamespace) -> Callable[[List[str]], str]:
+    """ SimulEval detokenizer from https://github.com/facebookresearch/SimulEval/blob/
+    536de8253b82d805c9845440169a5010ff507357/simuleval/evaluator/instance.py#L233"""
+    if config.latency_unit == "word":
+        def detokenize(input_tokens: List[str]) -> str:
+            return " ".join(input_tokens)
+    elif config.latency_unit == "char":
+        def detokenize(input_tokens: List[str]) -> str:
+            return "".join(input_tokens)
+    elif config.latency_unit == "spm":
+        def detokenize(input_tokens: List[str]) -> str:
+            return "".join(input_tokens).replace("▁", " ").strip()
+    else:
+        raise NotImplementedError
+
+    return detokenize
+
+
+_DETOKENIZER_BUILDER_MAP: Dict[str, Callable[[SimpleNamespace], Callable[[List[str]], str]]] = {
+    "hf": build_hf_detokenizer,
+    "canary": build_canary_detokenizer,
+    "simuleval": build_simuleval_detokenizer
+}
+
+
+def get_detokenizer(config: SimpleNamespace) -> Callable[[List[str]], str]:
+    return _DETOKENIZER_BUILDER_MAP[config.detokenizer_type](config)

simulstream/metrics/logger.py

@@ -0,0 +1,32 @@
+# Copyright 2025 FBK
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License
+
+import logging
+
+
+METRICS_LOGGER = logging.getLogger('fbk_fairseq.simultaneous.metrics')
+METRICS_LOGGER.propagate = False
+
+
+def setup_metrics_logger(metrics_config):
+    if metrics_config.enabled:
+        fh = logging.FileHandler(metrics_config.filename)
+        formatter = logging.Formatter('%(message)s')
+        fh.setFormatter(formatter)
+
+        # Clear existing handlers (if any) and set new one
+        METRICS_LOGGER.handlers.clear()
+        METRICS_LOGGER.addHandler(fh)
+    else:
+        METRICS_LOGGER.disabled = True