EchoScript : two fully independent pipelines, chosen explicitly, never both from one click : Transcript & Translations vs. Phonetic Transcription (IPA)

app.py

@@ -1,25 +1,43 @@
 """EchoScript v1.0 UI.
 
-Two-stage workflow, matching the frozen v1.0 product spec exactly:
-
-    Upload Audio -> Select Audio Window (optional)
-                  -> Detect Language & Generate Canonical Transcript
-                  -> Preview Transcript + available translation languages
-                  -> Generate Translations -> Copy / Download
-
-These are two distinct user actions, not one combined click:
+Two independent, mutually exclusive processing pipelines, chosen per
+click -- not two steps of one pipeline:
+
+    Transcript & Translations pipeline:
+        Upload Audio -> Select Audio Window (optional)
+                      -> Detect Language & Generate Canonical Transcript
+                      -> Preview Transcript + available translation languages
+                      -> Generate Translations -> Copy / Download
+
+    Phonetic Transcription (IPA) pipeline:
+        Upload Audio -> Select Audio Window (optional)
+                      -> Generate Phonetic Transcription -> Copy / Download
+
+These never run together from the same click. That's deliberate: the
+Transcript pipeline treats the Transcript as the single source of truth
+for every translation and subtitle it produces, and the Phonetics
+pipeline reads the audio directly with no dependency on -- or influence
+from -- the Transcript at all (see services/phonetics.py for why that
+independence matters). Mixing them into one combined action would mean
+either running Whisper when someone only wanted IPA phones, or running
+the phone recognizer when someone only wanted a transcript -- both
+wasted work, and it would blur which of the two "touches the audio"
+for a given result.
+
+Within the Transcript pipeline, "Generate Transcript" and "Generate
+Translations" remain two distinct actions:
 
 1. "Generate Transcript" -- audio, time window, and an optional source-
    language hint go in; a canonical Transcript comes out (detected
    language, confidence, duration, word count, full text). This is the
-   only step that touches the audio. Once it's done, the translation-
-   language picker appears, scoped to the language that was *actually*
-   detected (or forced) -- never a pre-detection guess.
+   only step that touches the audio in this pipeline. Once it's done,
+   the translation-language picker appears, scoped to the language that
+   was *actually* detected (or forced) -- never a pre-detection guess.
 2. "Generate Translations" -- pick which languages to translate the
    transcript into (the list depends on whether an Anthropic API key is
    present: more languages with a key, the offline-safe set without one)
-   and click again. Always derived from the cached Transcript, never from
-   the audio.
+   and click again. Always derived from the cached Transcript, never
+   from the audio.
 
 Caching: a `gr.State` holds the last Transcript plus the exact (audio,
 window, source-language) signature that produced it -- clicking "Generate
@@ -28,6 +46,8 @@ re-running Whisper. A second `gr.State` dict caches each Translation by
 language code, scoped to the current transcript, so adding one more
 language to "Generate Translations" doesn't redo the others, and
 deselecting a language doesn't drop it from the cache (just hides it).
+The Phonetics pipeline has its own, separate cache/signature pair, keyed
+only on (audio, window) -- it has no source-language concept at all.
 
 Services are instantiated lazily (on first use) rather than at import
 time, so the app can start up without needing model weights on disk yet.
@@ -43,6 +63,7 @@ import gradio as gr
 
 from models.transcript import Transcript
 from services.audio import AudioError, extract_window, resolve_window, validate_extension
+from services.phonetics import PhoneticsError, transcribe_phonetics
 from services.subtitles import generate_srt, generate_vtt
 from services.transcription import SUPPORTED_LANGUAGES, TranscriptionService
 from services.translation import (
@@ -151,6 +172,7 @@ def generate_transcript(
     cached_signature,
     cached_translations: dict,
 ):
+    """Transcript & Translations mode. Never touches the phonetics engine."""
     if not audio_path:
         raise gr.Error("Please upload an audio file first.")
 
@@ -172,8 +194,7 @@ def generate_transcript(
             except AudioError as exc:
                 raise gr.Error(str(exc)) from exc
 
-        # The only step that touches the audio. Detection happens here too
-        # when no source language is forced.
+        # The only step that touches the audio in this mode.
         transcript = get_transcription_service().transcribe(
             working_path,
             source_filename=Path(audio_path).name,
@@ -206,7 +227,7 @@ def generate_transcript(
     # never against a pre-detection guess.
     has_key = bool((api_key or "").strip())
     translation_choices = _compute_translation_choices(has_key, transcript.language)
-    default_targets = ["English Translation"] if "English Translation" in translation_choices else []
+    default_targets = ["English"] if "English" in translation_choices else []
     translate_choices_update = gr.update(choices=translation_choices, value=default_targets)
 
     srt_path = _write_text_file(generate_srt(transcript.segments), tmp_dir, "transcript.srt")
@@ -236,6 +257,59 @@ def generate_transcript(
     return outputs
 
 
+# ---------------------------------------------------------------------------
+# Alternate Stage 1: Generate Phonetic Transcription (IPA)
+#
+# Mutually exclusive with "Generate Transcript" -- this mode never touches
+# Whisper, never produces a Transcript, and therefore never feeds
+# translations or subtitles. It exists precisely so the Transcript can
+# stay the single source of truth for everything downstream of it: if you
+# want IPA phones, you get *only* IPA phones from this click, not a
+# transcript-plus-phonetics bundle. See services/phonetics.py for why this
+# needs to read the audio directly rather than derive from a transcript.
+# ---------------------------------------------------------------------------
+
+def generate_phonetics(
+    audio_path: Optional[str],
+    start_value: str,
+    end_value: str,
+    cached_phonetics: Optional[str],
+    cached_phonetics_signature,
+):
+    if not audio_path:
+        raise gr.Error("Please upload an audio file first.")
+
+    try:
+        validate_extension(audio_path)
+        start, end = resolve_window(start_value, end_value)
+    except AudioError as exc:
+        raise gr.Error(str(exc)) from exc
+
+    signature = (audio_path, start, end)
+    if cached_phonetics is not None and cached_phonetics_signature == signature:
+        # Same audio and window as last time -- reuse rather than
+        # re-running the phone recognizer.
+        phonetics_text = cached_phonetics
+    else:
+        working_path = audio_path
+        if start is not None or end is not None:
+            try:
+                working_path = extract_window(audio_path, start, end)
+            except AudioError as exc:
+                raise gr.Error(str(exc)) from exc
+
+        try:
+            phonetics_text = transcribe_phonetics(working_path)
+        except PhoneticsError as exc:
+            phonetics_text = f"\u26a0\ufe0f Phonetic transcription failed: {exc}"
+        cached_phonetics_signature = signature
+
+    tmp_dir = Path(tempfile.mkdtemp(prefix="echoscript_"))
+    phonetics_file = _write_text_file(phonetics_text, tmp_dir, "phonetics.txt")
+
+    return [phonetics_text, phonetics_file, phonetics_text, cached_phonetics_signature]
+
+
 # ---------------------------------------------------------------------------
 # Stage 2: Generate Translations
 # ---------------------------------------------------------------------------
@@ -324,8 +398,8 @@ def generate_translations(
         yield _make_outputs(section_states)
 
 
-def reset_session_state():
-    """Clear cached transcript/translations and everything on screen."""
+def reset_transcript_state():
+    """Clear cached transcript/translations and everything on screen for that mode."""
     ui_reset = [
         "Upload an audio file and click **Generate Transcript** to begin.",
         "",
@@ -340,6 +414,11 @@ def reset_session_state():
     return ui_reset
 
 
+def reset_phonetics_state():
+    """Clear cached phonetics and everything on screen for that mode."""
+    return ["", None, None, None]
+
+
 # ---------------------------------------------------------------------------
 # UI layout
 # ---------------------------------------------------------------------------
@@ -349,15 +428,17 @@ with gr.Blocks(title="EchoScript") as demo:
     transcript_state = gr.State(value=None)
     signature_state = gr.State(value=None)
     translations_state = gr.State(value={})
+    phonetics_state = gr.State(value=None)
+    phonetics_signature_state = gr.State(value=None)
 
     gr.Markdown(
         """
 # EchoScript
 
-**Upload Audio → Select Audio Window → Detect Language & Generate Transcript
-→ Preview & Choose Languages → Generate Translations → Copy / Download**
+**Upload Audio → Choose Transcript or Phonetics (independent pipelines) → Preview &
+Choose Languages (Transcript mode only) → Generate Translations → Copy / Download**
 
-<sub>build: 2026-07-02 23:46 UTC &middot; microphone input added</sub>
+<sub>build: 2026-07-06 22:10 UTC &middot; Transcript and Phonetics are now independent, mutually exclusive pipelines</sub>
         """
     )
 
@@ -378,27 +459,45 @@ with gr.Blocks(title="EchoScript") as demo:
                 end_input = gr.Textbox(label="End Time (optional)", placeholder="HH:MM:SS")
             gr.Markdown("Leave blank: entire file")
 
-            gr.Markdown("### Processing Options")
-            language_input = gr.Dropdown(
-                choices=SOURCE_LANGUAGE_CHOICES,
-                value="Auto Detect",
-                label="Source Language",
-                info="A hint for transcription, not a guess at translation targets.",
+            gr.Markdown("### What do you want to generate?")
+            gr.Markdown(
+                "These are two independent pipelines -- choose one per click. "
+                "**Transcript** is the source of truth for translations, subtitles, "
+                "and editing. **Phonetics** reads the audio directly and has no "
+                "connection to the transcript at all -- it won't 'correct' toward "
+                "real words the way a transcript does, and picking it here never "
+                "runs (or requires) the transcript pipeline."
             )
 
-            api_key_input = gr.Textbox(
-                label="Anthropic API Key (optional)",
-                type="password",
-                placeholder="sk-ant-...",
-                info=(
-                    "Provide your own key to translate into many more languages via Claude. "
-                    "Without one, translation uses local offline models (English, German, "
-                    "Persian, Spanish only). Used for this session only -- never stored."
-                ),
-            )
+            with gr.Tabs():
+                with gr.Tab("Transcript & Translations"):
+                    language_input = gr.Dropdown(
+                        choices=SOURCE_LANGUAGE_CHOICES,
+                        value="Auto Detect",
+                        label="Source Language",
+                        info="A hint for transcription, not a guess at translation targets.",
+                    )
+                    api_key_input = gr.Textbox(
+                        label="Anthropic API Key (optional)",
+                        type="password",
+                        placeholder="sk-ant-...",
+                        info=(
+                            "Provide your own key to translate into many more languages via "
+                            "Claude. Without one, translation uses local offline models "
+                            "(English, German, Persian, Spanish, and more). Used for this "
+                            "session only -- never stored."
+                        ),
+                    )
+                    generate_transcript_button = gr.Button("Generate Transcript", variant="primary")
+                    reset_transcript_button = gr.Button("Reset Transcript (clear cache)", size="sm")
 
-            generate_transcript_button = gr.Button("Generate Transcript", variant="primary")
-            reset_button = gr.Button("Reset (clear cache)", size="sm")
+                with gr.Tab("Phonetic Transcription (IPA)"):
+                    gr.Markdown(
+                        "Produces the exact IPA sounds heard in the audio -- "
+                        "independent of language, and independent of the transcript."
+                    )
+                    generate_phonetics_button = gr.Button("Generate Phonetic Transcription", variant="primary")
+                    reset_phonetics_button = gr.Button("Reset Phonetics (clear cache)", size="sm")
 
         with gr.Column(scale=2):
             gr.Markdown("### Results Dashboard")
@@ -414,6 +513,22 @@ with gr.Blocks(title="EchoScript") as demo:
                     )
                     transcript_download = gr.DownloadButton("Download TXT")
 
+                with gr.Tab("Phonetics (IPA)"):
+                    gr.Markdown(
+                        "The exact sounds heard in the audio, written as IPA phones -- "
+                        "independent of any language. This is **not** derived from the "
+                        "transcript: it comes from a universal phone recognizer reading "
+                        "the audio directly, so it won't correct itself toward real words "
+                        "the way the transcript does."
+                    )
+                    phonetics_box = gr.Textbox(
+                        label="Phonetic transcription (IPA)",
+                        lines=10,
+                        interactive=True,
+                        buttons=["copy"],
+                    )
+                    phonetics_download = gr.DownloadButton("Download TXT")
+
                 with gr.Tab("Translations"):
                     translations_placeholder = gr.Markdown(
                         "Generate a transcript first to see the languages available to "
@@ -454,7 +569,7 @@ with gr.Blocks(title="EchoScript") as demo:
                         srt_download = gr.DownloadButton("Download SRT")
                         vtt_download = gr.DownloadButton("Download VTT")
 
-    # Outputs shared by Stage 1 (Generate Transcript) and Reset.
+    # Outputs for the Transcript & Translations mode (and its Reset).
     transcript_stage_outputs = [
         dashboard_output,
         transcript_box,
@@ -491,6 +606,18 @@ with gr.Blocks(title="EchoScript") as demo:
         ],
         outputs=transcript_stage_outputs,
     )
+    reset_transcript_button.click(fn=reset_transcript_state, outputs=transcript_stage_outputs)
+
+    # Outputs for the Phonetics mode (and its Reset) -- entirely separate
+    # from the transcript pipeline; sharing only the audio/window inputs.
+    phonetics_stage_outputs = [phonetics_box, phonetics_download, phonetics_state, phonetics_signature_state]
+
+    generate_phonetics_button.click(
+        fn=generate_phonetics,
+        inputs=[audio_input, start_input, end_input, phonetics_state, phonetics_signature_state],
+        outputs=phonetics_stage_outputs,
+    )
+    reset_phonetics_button.click(fn=reset_phonetics_state, outputs=phonetics_stage_outputs)
 
     # Outputs for Stage 2 (Generate Translations): just the per-language
     # sections plus the translation cache.
@@ -532,7 +659,5 @@ with gr.Blocks(title="EchoScript") as demo:
         outputs=[translate_choices_input],
     )
 
-    reset_button.click(fn=reset_session_state, outputs=transcript_stage_outputs)
-
 if __name__ == "__main__":
     demo.launch()

models/transcript.py

@@ -8,6 +8,16 @@ and must never reach back into the original audio.
 
     Audio -> Transcript -> Outputs   (allowed)
     Audio -> Translation             (never)
+
+Phonetic transcription (services/phonetics.py) is a separate, mutually
+exclusive pipeline, not a step alongside this one: the person chooses
+either "Generate Transcript" (this model, feeding translations/subtitles)
+or "Generate Phonetic Transcription" (reads the audio directly, IPA
+output, no Transcript involved at all) -- never both from the same audio
+in the same app.py action. This keeps Transcript the single, unambiguous
+source of truth for every translation, with no parallel audio-reading
+path that could make you wonder which one a downstream artifact came
+from. See services/phonetics.py and app.py's mode selector for why.
 """
 
 from __future__ import annotations

requirements.txt

@@ -6,3 +6,4 @@ sacremoses>=0.1
 torch>=2.0
 anthropic>=0.40
 huggingface_hub>=0.24
+allosaurus>=1.0.2

services/phonetics.py

@@ -0,0 +1,112 @@
+"""Phonetic transcription: Audio -> IPA phones, independent of language.
+
+This is deliberately NOT derived from the Transcript. Every other service
+in this codebase follows "Audio -> Transcript -> everything else" (see
+models/transcript.py's module docstring) -- phonetics is the one
+intentional exception, because the whole point is a representation of
+the raw acoustics that owes nothing to any language's orthography or to
+Whisper's language-modeled guess at "what words were probably said".
+
+Whisper's transcript is produced by a model that's biased toward
+producing valid words in some language -- it fills in gaps using
+linguistic context. What's implemented here is a *phone recognizer*:
+a model that outputs the IPA symbols for the sounds it hears, using a
+universal (language-agnostic) phone inventory, with no dictionary, no
+grammar, and no language identity involved at all. Two speakers of
+different languages making the same mouth sounds get the same IPA
+output from this service; they would NOT get the same Whisper transcript.
+
+Backend: Allosaurus (https://github.com/xinjli/allosaurus), a universal
+phone recognizer trained across ~2000 languages specifically to avoid
+being biased toward any single language's phoneme set. Its default
+inference mode (lang_id="ipa") is exactly this: no target-language
+assumption at all.
+
+Note: only .wav is accepted by Allosaurus directly. mp3/m4a/flac inputs
+are transcoded to a temporary wav first (see _ensure_wav below) --
+this is a format conversion, not a re-interpretation of content, so it
+doesn't violate the "independent of language" property.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import tempfile
+from functools import lru_cache
+from pathlib import Path
+from typing import Optional
+
+
+class PhoneticsError(RuntimeError):
+    """Raised when phonetic transcription can't be produced for this audio."""
+
+
+@lru_cache(maxsize=1)
+def _get_recognizer():
+    """Load (and cache) the Allosaurus universal phone recognizer.
+
+    Cached at module level deliberately: this is a large model with no
+    per-request state (unlike TranslationService's API key), so it's safe
+    and desirable to load it once and reuse it across every call in the
+    process, the same way TranscriptionService's Whisper model is reused.
+    """
+    try:
+        from allosaurus.app import read_recognizer
+    except ImportError as exc:
+        raise PhoneticsError(
+            "The 'allosaurus' package is not installed. Add it to "
+            "requirements.txt and reinstall to enable phonetic transcription."
+        ) from exc
+
+    try:
+        return read_recognizer()
+    except Exception as exc:
+        raise PhoneticsError(
+            f"Failed to load the Allosaurus phone recognizer: {exc}"
+        ) from exc
+
+
+def _ensure_wav(audio_path: str) -> tuple[str, Optional[Path]]:
+    """Return a path Allosaurus can read, converting to wav if necessary.
+
+    Returns (wav_path, temp_dir_to_clean_up_or_None). Allosaurus only
+    accepts .wav files; this is a lossless-in-content format conversion
+    (resample/remux), not a transcription step, so it has no bearing on
+    the language-independence of the result.
+    """
+    if audio_path.lower().endswith(".wav"):
+        return audio_path, None
+
+    tmp_dir = Path(tempfile.mkdtemp(prefix="echoscript_phon_"))
+    wav_path = tmp_dir / "audio.wav"
+
+    result = subprocess.run(
+        ["ffmpeg", "-y", "-i", str(audio_path), "-ar", "16000", "-ac", "1", str(wav_path)],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        raise PhoneticsError(f"ffmpeg failed to prepare audio for phonetic analysis: {result.stderr.strip()}")
+
+    return str(wav_path), tmp_dir
+
+
+def transcribe_phonetics(audio_path: str) -> str:
+    """Return the IPA phone sequence for this audio file, start to finish.
+
+    Operates directly on the (already time-windowed, if applicable) audio
+    file -- never on a Transcript. Uses Allosaurus's universal 'ipa' mode,
+    which makes no assumption about what language is being spoken.
+    """
+    wav_path, cleanup_dir = _ensure_wav(audio_path)
+    try:
+        recognizer = _get_recognizer()
+        try:
+            phones = recognizer.recognize(wav_path, lang_id="ipa")
+        except Exception as exc:
+            raise PhoneticsError(f"Allosaurus failed to process the audio: {exc}") from exc
+        return phones.strip()
+    finally:
+        if cleanup_dir is not None:
+            import shutil
+            shutil.rmtree(cleanup_dir, ignore_errors=True)