simulstream 0.2.0__tar.gz → 1.0.0__tar.gz

{simulstream-0.2.0/simulstream.egg-info → simulstream-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simulstream
-Version: 0.2.0
+Version: 1.0.0
 Summary: A server to run simultaneous/streaming experiments and demo
 Author-email: Marco Gaido <mgaido@fbk.eu>, FBK HLT-MT <mt@fbk.eu>
 License:                                  Apache License
@@ -215,6 +215,7 @@ Requires-Dist: pyyaml>6.0
 Requires-Dist: websockets
 Requires-Dist: torch
 Requires-Dist: librosa
+Requires-Dist: pycountry
 Provides-Extra: dev
 Requires-Dist: pytest==7.4.0; extra == "dev"
 Requires-Dist: flake8; extra == "dev"
@@ -226,7 +227,7 @@ Provides-Extra: hf
 Requires-Dist: transformers==4.48.1; extra == "hf"
 Provides-Extra: canary
 Requires-Dist: Cython; extra == "canary"
-Requires-Dist: nemo_toolkit[asr]==2.4.0; extra == "canary"
+Requires-Dist: nemo_toolkit[asr]==3.0.0; extra == "canary"
 Provides-Extra: vad
 Requires-Dist: silero-vad; extra == "vad"
 Provides-Extra: eval
@@ -414,14 +415,15 @@ can score your speech processor by running:
 simulstream_score_latency --scorer stream_laal \
     --eval-config config/speech_processor.yaml \
     --log-file metrics.jsonl \
-    --reference REFERENCE_FILE.txt \
+    --reference REFERENCES_FILE.tgt \
     --audio-definition YAML_AUDIO_REFERENCES_DEFINITION.yaml
 
 simulstream_score_quality --scorer comet \
     --eval-config config/speech_processor.yaml \
     --log-file metrics.jsonl \
-    --references REFERENCES_FILE.txt \
-    --transcripts TRANSCRIPTS_FILE.txt
+    --references REFERENCES_FILE.tgt \
+    --transcripts TRANSCRIPTS_FILE.src \
+    --audio-definition YAML_AUDIO_REFERENCES_DEFINITION.yaml
 
 simulstream_stats --eval-config config/speech_processor.yaml \
     --log-file metrics.jsonl
@@ -435,7 +437,20 @@ the selected metric (``--scorer``).
 
 Similarly, ``simulstream_score_quality`` evaluated the quality
 of the generated outputs against one (or more) reference (and transcript, only for metrics
-requiring them) file(s).
+requiring them) file(s). Here, the `YAML_AUDIO_REFERENCES_DEFINITION.yaml` has the same number of entries (sentence definitions
+in terms of wav file origin, offset and duration) as `REFERENCES_FILE.tgt` and `TRANSCRIPTS_FILE.src`.
+
+As an alternative, `simulstream_score_quality` can be run without the `--audio-definition` specification, by using a list of 
+files as arguments of `--references` and `--transcripts`. In this case, the name of the files (trimmed of the extension) 
+**must be the same** of the audio files used (i.e. the names present in `metrics.jsonl`). For instance:
+
+```
+simulstream_score_quality --scorer comet \
+    --eval-config config/speech_processor.yaml \
+    --log-file metrics.jsonl \
+    --references AUDIO1.tgt,AUDIO2.tgt,AUDIO3.tgt \
+    --transcripts AUDIO1.src,AUDIO2.src,AUDIO3.src
+```
 
 Lastly, ``simulstream_stats`` computes statistics like the computational cost and flickering ratio.
 

{simulstream-0.2.0 → simulstream-1.0.0}/README.md

@@ -177,14 +177,15 @@ can score your speech processor by running:
 simulstream_score_latency --scorer stream_laal \
     --eval-config config/speech_processor.yaml \
     --log-file metrics.jsonl \
-    --reference REFERENCE_FILE.txt \
+    --reference REFERENCES_FILE.tgt \
     --audio-definition YAML_AUDIO_REFERENCES_DEFINITION.yaml
 
 simulstream_score_quality --scorer comet \
     --eval-config config/speech_processor.yaml \
     --log-file metrics.jsonl \
-    --references REFERENCES_FILE.txt \
-    --transcripts TRANSCRIPTS_FILE.txt
+    --references REFERENCES_FILE.tgt \
+    --transcripts TRANSCRIPTS_FILE.src \
+    --audio-definition YAML_AUDIO_REFERENCES_DEFINITION.yaml
 
 simulstream_stats --eval-config config/speech_processor.yaml \
     --log-file metrics.jsonl
@@ -198,7 +199,20 @@ the selected metric (``--scorer``).
 
 Similarly, ``simulstream_score_quality`` evaluated the quality
 of the generated outputs against one (or more) reference (and transcript, only for metrics
-requiring them) file(s).
+requiring them) file(s). Here, the `YAML_AUDIO_REFERENCES_DEFINITION.yaml` has the same number of entries (sentence definitions
+in terms of wav file origin, offset and duration) as `REFERENCES_FILE.tgt` and `TRANSCRIPTS_FILE.src`.
+
+As an alternative, `simulstream_score_quality` can be run without the `--audio-definition` specification, by using a list of 
+files as arguments of `--references` and `--transcripts`. In this case, the name of the files (trimmed of the extension) 
+**must be the same** of the audio files used (i.e. the names present in `metrics.jsonl`). For instance:
+
+```
+simulstream_score_quality --scorer comet \
+    --eval-config config/speech_processor.yaml \
+    --log-file metrics.jsonl \
+    --references AUDIO1.tgt,AUDIO2.tgt,AUDIO3.tgt \
+    --transcripts AUDIO1.src,AUDIO2.src,AUDIO3.src
+```
 
 Lastly, ``simulstream_stats`` computes statistics like the computational cost and flickering ratio.
 

{simulstream-0.2.0 → simulstream-1.0.0}/pyproject.toml

@@ -14,7 +14,8 @@ dependencies = [
     "pyyaml>6.0",
     "websockets",
     "torch",
-    "librosa"
+    "librosa",
+    "pycountry"
 ]
 dynamic = ["version"]
 
@@ -52,7 +53,7 @@ hf = [
 
 canary = [
     "Cython",
-    "nemo_toolkit[asr]==2.4.0",
+    "nemo_toolkit[asr]==3.0.0",
 ]
 
 vad = [

simulstream-1.0.0/simulstream/VERSION.txt

@@ -0,0 +1 @@
+1.0.0

{simulstream-0.2.0 → simulstream-1.0.0}/simulstream/client/wav_reader_client.py

@@ -159,7 +159,11 @@ def load_wav_file_list(list_file_path: str) -> List[str]:
     """
     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()]
+        wav_files = [
+            line.strip() if os.path.isabs(line.strip())
+            else os.path.abspath(os.path.join(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)

{simulstream-0.2.0 → simulstream-1.0.0}/simulstream/inference.py

@@ -53,14 +53,10 @@ def process_audio(
     # one speech chunk is the following
     samples_per_chunk = int(
         sample_rate * message_processor.speech_processor.speech_chunk_size)
-    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(

{simulstream-0.2.0 → simulstream-1.0.0}/simulstream/metrics/score_quality.py

@@ -124,6 +124,19 @@ def cli_main():
             --log-file metrics.jsonl \\
             --references ref.en \\
             --transcripts src.it \\
+            --audio-definition audio_def.yaml \\
+            --scorer sacrebleu
+
+    Otherwise, the script can be invoked without specifying the `--audio-definition`,
+    but in this case the name of the refererence and transcript files (trimmed of
+    the extension) must be the same of the audio files used (i.e. the names present
+    in `metrics.jsonl`), e.g.:
+
+        $ python -m simulstream.metrics.score_quality \\
+            --eval-config config/speech-processor.yaml \\
+            --log-file metrics.jsonl \\
+            --references 1.en,2.en \\
+            --transcripts 1.it,2.it \\
             --scorer sacrebleu
     """
     LOGGER.info(f"Simulstream version: {simulstream.__version__}")
@@ -140,17 +153,23 @@ def cli_main():
              "specified, this should be a single file containing all the lines of the audios in "
              "the reference, which should be of the same length of the audio definition. "
              "Otherwise, this should be a list of files, where each contains the lines "
-             "corresponding to an audio file.")
+             "corresponding to an audio file. In the case of being a list of files, the file "
+             "stem must match a corresponding transcript for an audio file (if applicable "
+             "to the quality metric).")
     parser.add_argument(
         "--transcripts", nargs="+", type=str,
         help="Path to the textual files containing reference transcripts. If `--audio-definition` "
              "is specified, this should be a single file containing all the lines of the audios "
              "in the reference, which should be of the same length of the audio definition. "
              "Otherwise, this should be a list of files, where each contains the lines "
-             "corresponding to an audio file.")
+             "corresponding to an audio file. In the case of being a list of files, the file "
+             "stem must match a corresponding reference for an audio file.")
     parser.add_argument(
         "--audio-definition", "-a", type=str, default=None,
         help="Path to the yaml file containing the segment-level audio information.")
+    parser.add_argument(
+        "--latency-unit", choices=["char", "word"], default="word",
+        help="Whether to computed stats based on words or characters. Default: word.")
     parser.add_argument("--scorer", choices=QUALITY_SCORER_REGISTRY.keys(), required=True)
     args, _ = parser.parse_known_args()
 

{simulstream-0.2.0 → simulstream-1.0.0}/simulstream/metrics/scorers/latency/mwersegmenter.py

@@ -17,6 +17,7 @@ from dataclasses import dataclass
 from typing import List
 
 from mweralign import mweralign
+from mweralign.segmenter import CJSegmenter
 
 from simulstream.metrics.readers import ReferenceSentenceDefinition, OutputWithDelays, text_items
 from simulstream.metrics.scorers.latency import LatencyScorer, LatencyScoringSample, LatencyScores
@@ -58,6 +59,7 @@ class MWERSegmenterBasedLatencyScorer(LatencyScorer):
     def __init__(self, args):
         super().__init__(args)
         self.latency_unit = args.latency_unit
+        self.segmenter = CJSegmenter() if args.latency_unit == "char" else None
 
     def requires_reference(self) -> bool:
         return True
@@ -101,19 +103,50 @@ class MWERSegmenterBasedLatencyScorer(LatencyScorer):
             f"Index {index} should have reached end of delays ({len(delays)})"
         return segmented_delays
 
+    def _tokenize(self, text: List[str]) -> List[str]:
+        """
+        Tokenize text using the segmenter.
+
+        Borrowed from
+        https://github.com/mjpost/mweralign/blob/d23a5479/mweralign/mweralign.py#L147
+        """
+        if self.segmenter is not None:
+            tokenized_text = []
+            for i in range(len(text)):
+                if " ### " in text[i]:
+                    pieces = text[i].strip().split(" ### ")
+                    encoded = [" ".join(self.segmenter.encode(p)) for p in pieces]
+                    tokenized_text.append(" ### ".join(encoded))
+                elif "\t" in text[i]:
+                    pieces = text[i].strip().split("\t")
+                    # underlying C++ binary still uses ###
+                    encoded = [" ".join(self.segmenter.encode(p)) for p in pieces]
+                    tokenized_text.append(" ### ".join(encoded))
+                else:
+                    tokenized_text.append(" ".join(self.segmenter.encode(text[i])))
+            return "\n".join(tokenized_text)
+        else:
+            return "\n".join(text)
+
     def score(self, samples: List[LatencyScoringSample]) -> LatencyScores:
         resegmented_samples = []
         for sample in samples:
             assert sample.reference is not None, "Cannot realign hypothesis to missing reference"
 
-            resegmented_hypos = mweralign.align_texts(
-                "\n".join([sentence_def.content for sentence_def in sample.reference]),
-                sample.hypothesis.final_text).split("\n")
+            hypo = self._tokenize([sample.hypothesis.final_text])
+            refs = self._tokenize(
+                [sentence_def.content for sentence_def in sample.reference])
+            resegmented_hypos = mweralign.align_texts(refs, hypo).split("\n")
 
             assert len(resegmented_hypos) == len(sample.reference), \
                 f"Reference ({sample.audio_name}) has mismatched number of target " \
                 f"({len(sample.reference)}) and resegmented lines ({len(resegmented_hypos)})"
 
+            if self.segmenter is not None:
+                # segmenter.decode will strip() the spaces, but we need them to align with delays
+                resegmented_hypos = [
+                    hypo.replace(" ", "").replace("_", " ") for hypo in resegmented_hypos]
+
             ideal_delays_splits = self._split_delays_by_segmented_text(
                 sample.hypothesis.ideal_delays,
                 resegmented_hypos)

{simulstream-0.2.0 → simulstream-1.0.0}/simulstream/metrics/scorers/quality/comet.py

@@ -13,17 +13,13 @@
 # limitations under the License
 
 import argparse
-import sys
 from typing import List
 
 from simulstream.metrics.scorers.quality import register_quality_scorer
 from simulstream.metrics.scorers.quality.mwersegmenter import MWERSegmenterBasedQualityScorer, \
     ResegmentedQualityScoringSample
 
-try:
-    from comet import download_model, load_from_checkpoint
-except ImportError:
-    sys.exit("Please install comet first with `pip install unbabel-comet`.")
+from comet import download_model, load_from_checkpoint
 
 
 @register_quality_scorer("comet")

{simulstream-0.2.0 → simulstream-1.0.0}/simulstream/metrics/scorers/quality/mwersegmenter.py

@@ -17,6 +17,7 @@ from dataclasses import dataclass
 from typing import List, Optional
 
 from mweralign import mweralign
+from mweralign.segmenter import CJSegmenter
 
 from simulstream.metrics.scorers.quality import QualityScorer, QualityScoringSample
 
@@ -56,6 +57,11 @@ class MWERSegmenterBasedQualityScorer(QualityScorer):
         ...         # Compute a custom quality score
         ...         return ...
     """
+
+    def __init__(self, args):
+        super().__init__(args)
+        self.segmenter = CJSegmenter() if args.latency_unit == "char" else None
+
     def requires_reference(self) -> bool:
         return True
 
@@ -75,15 +81,48 @@ class MWERSegmenterBasedQualityScorer(QualityScorer):
         """
         ...
 
+    def _tokenize(self, text: List[str]) -> List[str]:
+        """
+        Tokenize text using the segmenter.
+
+        Borrowed from
+        https://github.com/mjpost/mweralign/blob/d23a5479/mweralign/mweralign.py#L147
+        """
+        if self.segmenter is not None:
+            tokenized_text = []
+            for i in range(len(text)):
+                if " ### " in text[i]:
+                    pieces = text[i].strip().split(" ### ")
+                    encoded = [" ".join(self.segmenter.encode(p)) for p in pieces]
+                    tokenized_text.append(" ### ".join(encoded))
+                elif "\t" in text[i]:
+                    pieces = text[i].strip().split("\t")
+                    # underlying C++ binary still uses ###
+                    encoded = [" ".join(self.segmenter.encode(p)) for p in pieces]
+                    tokenized_text.append(" ### ".join(encoded))
+                else:
+                    tokenized_text.append(" ".join(self.segmenter.encode(text[i].strip())))
+            return "\n".join(tokenized_text)
+        else:
+            return "\n".join(text)
+
     def score(self, samples: List[QualityScoringSample]) -> float:
         resegmented_samples = []
         for sample in samples:
             assert sample.reference is not None, "Cannot realign hypothesis to missing reference"
-            resegmented_hypos = mweralign.align_texts(
-                "\n".join(sample.reference), sample.hypothesis).split("\n")
+            hypo = self._tokenize([sample.hypothesis])
+            refs = self._tokenize(sample.reference)
+            resegmented_hypos = mweralign.align_texts(refs, hypo).split("\n")
+
             assert len(sample.reference) == len(resegmented_hypos), \
                 f"Reference ({sample.audio_name}) has mismatched number of target " \
                 f"({len(sample.reference)}) and resegmented lines ({len(resegmented_hypos)})"
+
+            if self.segmenter is not None:
+                # segmenter.decode will strip() the spaces, but we need them to align with delays
+                resegmented_hypos = [
+                    hypo.replace(" ", "").replace("_", " ") for hypo in resegmented_hypos]
+
             resegmented_samples.append(ResegmentedQualityScoringSample(
                 sample.audio_name,
                 resegmented_hypos,

simulstream-1.0.0/simulstream/server/speech_processors/base_doa.py

@@ -0,0 +1,230 @@
+# Copyright 2026 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
+from abc import abstractmethod
+from types import SimpleNamespace
+from typing import List, Tuple, Any, Dict
+
+import numpy as np
+import pycountry
+import torch
+
+from simulstream.server.speech_processors import SAMPLE_RATE
+from simulstream.server.speech_processors.base_streamatt import BaseStreamAtt
+
+
+logger = logging.getLogger(__name__)
+
+
+def get_language_name(code: str) -> str:
+    """Return the language name for an ISO 639-1 code, falling back to the code itself."""
+    lang = pycountry.languages.get(alpha_2=code)
+    if lang is not None:
+        return lang.name
+    else:
+        logger.warning(f"Language code '{code}' not found in the language list. Using language "
+                       f"code directly in the prompt, but this can lead to unexpected behavior.")
+        return code
+
+
+class DecoderOnlyAttention(BaseStreamAtt):
+    """
+    Generic Decoder-only Attention-based policy for SpeechLLMs.
+
+    The class handles:
+       - Raw-waveform history accumulation.
+       - Greedy generation with ``output_attentions=True``.
+       - Building the proxy cross-attention matrix from self-attention weights.
+       - Applying the StreamAtt-based policy on the proxy cross-attention matrix.
+
+    The derived class should implement the following methods:
+        - **load_model**: Loads the model and processor.
+        - **build_prompt**: Builds the text prompt to use with audio inputs.
+        - **build_processor_inputs**: Builds model inputs from the rolling audio history.
+        - **_do_generate**: Returns newly-generated tokens and self-attention scores.
+        - **_find_audio_positions**: Returns the indices of audio tokens.
+
+    Args:
+       config (SimpleNamespace): Configuration object. The following additional attributes are
+           expected:
+           - **attn_layer (int)**: Layer from which to extract attention scores. Defaults to 0.
+           - **attn_head (int)**: Attention head to use. If not set, attention scores are averaged
+             over all heads.
+           - **average_attn_over_layers (bool)**: Whether to average the selected attention view
+             over all decoder layers. Defaults to True.
+           - **audio_history_max_duration (int)**: Maximum raw waveform length to keep in the
+             rolling history, in seconds. Defaults to 180.
+           - **max_new_tokens (int)**: Maximum tokens to generate per chunk. Defaults to 32.
+    """
+
+    def __init__(self, config: SimpleNamespace):
+        super().__init__(config)
+        self.cross_attn_layer = getattr(self.config, "attn_layer", 0)
+        self.cross_attn_head = getattr(self.config, "attn_head", None)
+        self.average_attn_over_layers = getattr(self.config, "average_attn_over_layers", True)
+        self.audio_history_max_duration = getattr(self.config, "audio_history_max_duration", 180)
+        self.device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+        self.max_new_tokens = getattr(self.config, "max_new_tokens", 32)
+        self.prompt = getattr(self.config, "prompt", "Translate the audio to {tgt_lang}:")
+        logger.debug("Prompt:\n%s", self.prompt)
+
+    @property
+    def audio_max_len(self) -> int:
+        """Maximum raw-waveform samples to keep in the rolling audio history."""
+        return self.audio_history_max_duration * SAMPLE_RATE
+
+    @abstractmethod
+    def load_model(self, config: SimpleNamespace) -> None:
+        """
+        Load the model and processor from *config* and assign them to ``self.model`` and
+        ``self.processor``.
+
+        The model **must** be loaded with ``output_attentions=True`` (or the equivalent flag for
+        the architecture) and ``_attn_implementation="eager"``.
+        """
+        ...
+
+    @abstractmethod
+    def build_prompt(self) -> str:
+        """
+        Return the prompt string to be used with audio tokens.
+        """
+        ...
+
+    @abstractmethod
+    def build_processor_inputs(self, waveform: np.ndarray) -> Any:
+        """
+        Build processor inputs from the entire rolling waveform history (float32, 16 kHz).
+        """
+        ...
+
+    @abstractmethod
+    def _do_generate(self, inputs: Dict[str, Any]) -> Tuple[List[str], List[torch.Tensor]]:
+        """
+        Runs the actual generation from the underlying model and returns the generated tokens and
+        the corresponding self-attention scores.
+        """
+        ...
+
+    @abstractmethod
+    def _find_audio_positions(self, input_ids: torch.Tensor) -> torch.Tensor:
+        """Return token positions corresponding to the encoded audio span."""
+        ...
+
+    def _generate(self, waveform: np.ndarray) -> Tuple[List[str], torch.Tensor]:
+        """
+        Generate tokens from the given inputs together with the self-attention scores.
+
+        Returns:
+            Tuple[List[str], torch.Tensor]:
+                List[str]: A list of generated tokens.
+                torch.Tensor: Self-attention scores between speech and text with dimension
+                (token_len, audio_len).
+        """
+        inputs = self.build_processor_inputs(waveform).to(self.device)
+        input_ids = inputs["input_ids"]  # (1, input_len)
+        input_len = input_ids.shape[1]
+
+        audio_positions = self._find_audio_positions(input_ids)
+        audio_len = audio_positions.shape[0]
+
+        # Run the actual generate on the underlying model
+        new_tokens, attentions = self._do_generate(inputs)
+
+        # Build proxy cross-attention for the hypothesis (prefix + new_tokens)
+        prefill_attn = self.average_attn(attentions[0])
+        prefix_len = len(self.text_history) if self.text_history else 0
+        if prefix_len > 0:
+            # Prefix rows come from the prefill pass
+            prefix_rows = prefill_attn[input_len - prefix_len:, :][:, audio_positions]
+        else:
+            prefix_rows = torch.zeros(0, audio_len, device=self.device)
+
+        if new_tokens:
+            # The prefill pass predicts the first generated token, so its last row corresponds to
+            # the first generated token's proxy audio-attention
+            first_new_row = prefill_attn[-1:, audio_positions]
+            # Other tokens' attention is present in each generation step
+            new_rows = [
+                self.average_attn(step_attn).squeeze(0)[audio_positions]
+                for step_attn in attentions[1:]
+            ]
+            subsequent_new_attn = torch.stack(new_rows, dim=0)
+            new_attn = torch.cat([first_new_row, subsequent_new_attn], dim=0)
+        else:
+            new_attn = torch.zeros(0, audio_len, device=self.device)
+
+        cross_attn = torch.cat([prefix_rows, new_attn], dim=0)
+        cross_attn = self.normalize_attn(cross_attn)
+        return new_tokens, cross_attn
+
+    def set_target_language(self, language: str) -> None:
+        self.tgt_lang = language
+
+    def set_source_language(self, language: str) -> None:
+        self.src_lang = language
+
+    def build_raw_text_prefix(self) -> str:
+        return "".join(self.text_history) if self.text_history else ""
+
+    def _select_attn_from_layer(self, layer_attn: torch.Tensor) -> torch.Tensor:
+        # Generation runs one stream at a time, so remove the singleton batch dimension.
+        layer_attn = layer_attn.squeeze(0)
+        if self.cross_attn_head is None:
+            # Default behavior: average over all heads for this layer.
+            return layer_attn.mean(dim=0)
+
+        num_heads = layer_attn.shape[0]
+        if self.cross_attn_head < 0 or self.cross_attn_head >= num_heads:
+            raise ValueError(
+                f"Invalid attn_head={self.cross_attn_head}. Layer has {num_heads} heads."
+            )
+        return layer_attn[self.cross_attn_head]
+
+    def average_attn(self, attn) -> torch.Tensor:
+        """
+        Average or select attentions according to ``attn_layer``, ``attn_head``, and
+        ``average_attn_over_layers``.
+
+        If ``attn_head`` is not set, attention is averaged over heads. If
+        ``average_attn_over_layers`` is set, the selected per-layer attention view is also
+        averaged across layers; otherwise only ``attn_layer`` is used.
+        """
+        if self.average_attn_over_layers:
+            # Average the per-layer attention view selected by _select_attn_from_layer.
+            return torch.stack(
+                [self._select_attn_from_layer(layer_attn) for layer_attn in attn],
+                dim=0,
+            ).mean(dim=0)
+        return self._select_attn_from_layer(attn[self.cross_attn_layer])
+
+    def _preprocess(self, waveform: np.float32) -> np.ndarray:
+        """
+        Append *waveform* to ``self.audio_history`` and enforce the maximum length.
+        """
+        if self.audio_history is None:
+            self.audio_history = waveform
+        else:
+            self.audio_history = np.concatenate([self.audio_history, waveform])
+
+        if len(self.audio_history) > self.audio_max_len:
+            logger.warning("Audio history exceeded %d samples; trimming.", self.audio_max_len)
+            self.audio_history = self.audio_history[-self.audio_max_len:]
+
+        return self.audio_history
+
+    def tokens_to_string(self, tokens: List[str]) -> str:
+        """Convert a list of decoded tokens to a plain output string."""
+        return "".join(tokens)