EchoScript : UI/UX Change , Stage 1 - Generate Transcript , Stage 1 - Generate Transcript

app.py

@@ -1,36 +1,36 @@
 """EchoScript v1.0 UI.
 
-Implements the frozen v1.0 workflow:
-
-    Upload Audio -> Generate Canonical Transcript -> Preview Results
-                  -> Generate Outputs -> Copy / Download
-
-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, and so
-this module stays import-safe in environments without network access.
-
-Two things make repeated clicks cheap:
-
-1. Transcript caching. A `gr.State` holds the last Transcript together with
-   the exact (audio path, time window, source language) signature that
-   produced it. If "Generate Outputs" is clicked again with that signature
-   unchanged -- e.g. only the Outputs checkboxes changed -- transcription
-   is skipped entirely and the cached Transcript is reused.
-2. Per-language translation caching. A second `gr.State` dict caches each
-   Translation by language code, scoped to the current transcript
-   signature. Selecting an additional language only translates that new
-   language; languages already translated (even if briefly deselected and
-   reselected) are reused rather than recomputed.
-
-Available translation languages are cascaded from two things:
-
-- Whether an Anthropic API key is present for this session (see
-  services/translation.py for the offline-vs-Claude tradeoff). The key is
-  used only for the request(s) made during this session and is never
-  written to disk, logged, or cached anywhere server-side.
-- The source language, explicit or detected: translating a language into
-  itself isn't offered. If "Auto Detect" is used, the list is re-filtered
-  once the actual language is known, after transcription.
+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:
+
+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.
+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.
+
+Caching: a `gr.State` holds the last Transcript plus the exact (audio,
+window, source-language) signature that produced it -- clicking "Generate
+Transcript" again with that signature unchanged reuses it instead of
+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).
+
+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.
 """
 
 from __future__ import annotations
@@ -53,13 +53,8 @@ from services.translation import (
 )
 
 # ---------------------------------------------------------------------------
-# Lazy service singletons
-#
-# Safe to share across requests/users: TranscriptionService holds no
-# per-request state, and TranslationService resolves its backend (and
-# takes the API key, if any) fresh on every translate() call rather than
-# storing it -- see services/translation.py. Per-request caching of
-# results (not the services themselves) lives in gr.State, below.
+# Lazy service singletons -- safe to share across requests/users; see
+# services/translation.py for why TranslationService holds no key state.
 # ---------------------------------------------------------------------------
 
 _transcription_service: Optional[TranscriptionService] = None
@@ -100,32 +95,33 @@ _TRANSLATION_LABEL_TO_CODE = {
 }
 
 # Sections are pre-built for every language in the full superset (hidden by
-# default) so that toggling the API key or source language never needs to
-# add/remove components -- only which ones are visible changes.
+# default) so that toggling the API key never needs to add/remove
+# components -- only which ones are visible changes.
 _TRANSLATION_SECTION_ORDER = list(_TRANSLATION_LABEL_TO_CODE.keys())
 
-DEFAULT_OUTPUTS = ["Transcript", "English Translation"]
 
-
-def _compute_output_choices(has_key: bool, exclude_code: Optional[str]) -> list[str]:
-    """The Outputs checkbox list, cascaded from key presence + source language.
+def _compute_translation_choices(has_key: bool, exclude_code: Optional[str]) -> list[str]:
+    """The translate-to picker, cascaded from key presence + source language.
 
     `exclude_code` removes "translate into the language it's already in"
-    from the list -- it's the explicit source language if one was chosen,
-    or the detected language once transcription has run.
+    -- always the actual transcript language at this point (this picker
+    only exists once a Transcript does), never a pre-detection guess.
     """
     pool = ANTHROPIC_TARGET_LANGUAGES if has_key else MARIAN_TARGET_LANGUAGES
-    return ["Transcript"] + [
-        f"{name} Translation" for code, name in pool.items() if code != exclude_code
-    ]
+    return [f"{name} Translation" for code, name in pool.items() if code != exclude_code]
 
 
-def _on_key_or_source_change(api_key: str, source_language_label: str, current_value: list[str]):
-    """Re-cascade the Outputs choices when the API key or source language changes."""
+def _on_api_key_change(api_key: str, cached_transcript: Optional[Transcript], current_value: list[str]):
+    """Re-cascade the translate-to picker live as the API key field changes.
+
+    No-op until a transcript exists -- the picker isn't shown before then,
+    so there's nothing yet to cascade.
+    """
+    if cached_transcript is None:
+        return gr.update()
     has_key = bool((api_key or "").strip())
-    exclude_code = _NAME_TO_CODE.get(source_language_label)  # None when "Auto Detect"
-    choices = _compute_output_choices(has_key, exclude_code)
-    filtered_value = [v for v in (current_value or []) if v in choices] or ["Transcript"]
+    choices = _compute_translation_choices(has_key, cached_transcript.language)
+    filtered_value = [v for v in (current_value or []) if v in choices]
     return gr.update(choices=choices, value=filtered_value)
 
 
@@ -143,15 +139,14 @@ def _write_text_file(text: str, tmp_dir: Path, filename: str) -> str:
 
 
 # ---------------------------------------------------------------------------
-# Main processing callback
+# Stage 1: Generate Transcript
 # ---------------------------------------------------------------------------
 
-def process_audio(
+def generate_transcript(
     audio_path: Optional[str],
     start_value: str,
     end_value: str,
     source_language_label: str,
-    selected_outputs: list[str],
     api_key: str,
     cached_transcript: Optional[Transcript],
     cached_signature,
@@ -168,13 +163,9 @@ def process_audio(
 
     source_code = _NAME_TO_CODE.get(source_language_label)  # None = auto-detect
     signature = (audio_path, start, end, source_code)
+    regenerated = not (cached_transcript is not None and cached_signature == signature)
 
-    if cached_transcript is not None and cached_signature == signature:
-        # Same file, same window, same forced source language as last time
-        # -- the canonical Transcript hasn't changed, so skip Whisper
-        # entirely and reuse it.
-        transcript = cached_transcript
-    else:
+    if regenerated:
         working_path = audio_path
         if start is not None or end is not None:
             try:
@@ -182,8 +173,8 @@ def process_audio(
             except AudioError as exc:
                 raise gr.Error(str(exc)) from exc
 
-        # Step 1: Audio -> canonical Transcript. This is the only step
-        # that touches the audio; everything below works off `transcript`.
+        # The only step that touches the audio. Detection happens here too
+        # when no source language is forced.
         transcript = get_transcription_service().transcribe(
             working_path,
             source_filename=Path(audio_path).name,
@@ -193,10 +184,13 @@ def process_audio(
         )
         cached_signature = signature
         cached_translations = {}  # old translations were derived from a different transcript
+    else:
+        # Same audio, window, and source-language hint as last time --
+        # skip Whisper entirely and reuse the cached Transcript.
+        transcript = cached_transcript
 
     tmp_dir = Path(tempfile.mkdtemp(prefix="echoscript_"))
 
-    # --- Results dashboard ---
     detected_language = SUPPORTED_LANGUAGES.get(transcript.language, transcript.language)
     dashboard_md = (
         f"### \u2713 {detected_language} detected\n\n"
@@ -205,29 +199,63 @@ def process_audio(
         f"**Words:** {transcript.word_count:,}"
     )
 
-    # Now that the actual language is known (important when "Auto Detect"
-    # was used), re-cascade the Outputs choices to drop "translate into
-    # the language it's already in" and drop that selection if it was
-    # only chosen by default/before detection.
-    has_key = bool((api_key or "").strip())
-    updated_choices = _compute_output_choices(has_key, transcript.language)
-    effective_outputs = [v for v in selected_outputs if v in updated_choices] or ["Transcript"]
-    outputs_update = gr.update(choices=updated_choices, value=effective_outputs)
-
-    # --- Transcript section (always computed -- it's the source of truth
-    # -- but only exposed if the user kept "Transcript" checked) ---
     transcript_text = transcript.text
     transcript_file = _write_text_file(transcript_text, tmp_dir, "transcript.txt")
-    transcript_visible = "Transcript" in effective_outputs
 
-    # --- Translations: reuse anything already cached for this transcript;
-    # only compute the languages newly selected since the last click. ---
+    # Now that the actual language is known -- the whole point of doing
+    # this as its own step -- compute the translate-to picker against it,
+    # 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 []
+    translate_choices_update = gr.update(choices=translation_choices, value=default_targets)
+
+    srt_path = _write_text_file(generate_srt(transcript.segments), tmp_dir, "transcript.srt")
+    vtt_path = _write_text_file(generate_vtt(transcript.segments), tmp_dir, "transcript.vtt")
+
+    # Per-language result sections: only reset (hide + clear) if the
+    # transcript actually changed. If it was reused, leave whatever
+    # translations are already showing exactly as they are.
+    section_outputs = []
+    if regenerated:
+        for _ in _TRANSLATION_SECTION_ORDER:
+            section_outputs += [gr.update(visible=False), "", None]
+    else:
+        for _ in _TRANSLATION_SECTION_ORDER:
+            section_outputs += [gr.update(), gr.update(), gr.update()]
+
+    outputs = [
+        dashboard_md,
+        transcript_text,
+        transcript_file,
+        translate_choices_update,
+        gr.update(visible=True),   # reveal the "choose languages" picker
+        gr.update(visible=False),  # hide the "generate a transcript first" placeholder
+    ]
+    outputs += section_outputs
+    outputs += [srt_path, vtt_path, transcript, cached_signature, cached_translations]
+    return outputs
+
+
+# ---------------------------------------------------------------------------
+# Stage 2: Generate Translations
+# ---------------------------------------------------------------------------
+
+def generate_translations(
+    selected_languages: list[str],
+    api_key: str,
+    cached_transcript: Optional[Transcript],
+    cached_translations: dict,
+):
+    if cached_transcript is None:
+        raise gr.Error("Generate a transcript first.")
+
     translation_service = get_translation_service()
-    section_updates = {}  # label -> (visible, text, file_path)
+    section_updates = {}
 
     for label in _TRANSLATION_SECTION_ORDER:
         code = _TRANSLATION_LABEL_TO_CODE[label]
-        if label not in effective_outputs:
+        if label not in (selected_languages or []):
             section_updates[label] = (False, "", None)
             continue
 
@@ -235,56 +263,42 @@ def process_audio(
             text = cached_translations[code]
         else:
             try:
-                translation = translation_service.translate(transcript, code, api_key=api_key)
+                translation = translation_service.translate(cached_transcript, code, api_key=api_key)
                 text = translation.text
                 cached_translations[code] = text
             except TranslationError as exc:
-                # Surface the failure in that section rather than aborting
-                # every other output that already succeeded. Deliberately
-                # not cached, so it's retried on the next click.
+                # Surface the failure for this language only; deliberately
+                # not cached, so the next click retries it.
                 text = f"\u26a0\ufe0f Translation failed: {exc}"
 
         file_path = None
         if not text.startswith("\u26a0\ufe0f"):
+            tmp_dir = Path(tempfile.mkdtemp(prefix="echoscript_"))
             file_path = _write_text_file(text, tmp_dir, f"{code}.txt")
         section_updates[label] = (True, text, file_path)
 
-    # --- Subtitles (always derived from the transcript, the canonical
-    # source of truth -- never regenerated from audio) ---
-    srt_path = _write_text_file(generate_srt(transcript.segments), tmp_dir, "transcript.srt")
-    vtt_path = _write_text_file(generate_vtt(transcript.segments), tmp_dir, "transcript.vtt")
-
-    outputs = [
-        dashboard_md,
-        transcript_text,
-        transcript_file,
-        gr.update(visible=transcript_visible),
-        outputs_update,
-    ]
-
+    outputs = []
     for label in _TRANSLATION_SECTION_ORDER:
         visible, text, file_path = section_updates[label]
         outputs += [gr.update(visible=visible), text, file_path]
-
-    outputs += [srt_path, vtt_path, transcript, cached_signature, cached_translations]
-
+    outputs.append(cached_translations)
     return outputs
 
 
 def reset_session_state():
-    """Clear cached transcript/translations and the visible results."""
-    cleared = [None, None, {}]
+    """Clear cached transcript/translations and everything on screen."""
     ui_reset = [
-        "Upload an audio file and click **Generate Outputs** to begin.",
+        "Upload an audio file and click **Generate Transcript** to begin.",
         "",
         None,
+        gr.update(choices=[], value=[]),
+        gr.update(visible=False),
         gr.update(visible=True),
-        gr.update(choices=_compute_output_choices(has_key=False, exclude_code=None), value=DEFAULT_OUTPUTS),
     ]
     for _ in _TRANSLATION_SECTION_ORDER:
         ui_reset += [gr.update(visible=False), "", None]
-    ui_reset += [None, None]
-    return ui_reset + cleared
+    ui_reset += [None, None, None, None, {}]
+    return ui_reset
 
 
 # ---------------------------------------------------------------------------
@@ -301,9 +315,10 @@ with gr.Blocks(title="EchoScript") as demo:
         """
 # EchoScript
 
-**Upload Audio → Generate Canonical Transcript → Preview Results → Generate Outputs → Copy / Download**
+**Upload Audio → Select Audio Window → Detect Language & Generate Transcript
+→ Preview & Choose Languages → Generate Translations → Copy / Download**
 
-<sub>build: 2026-06-26 19:40 UTC &middot; cascading-languages + caching</sub>
+<sub>build: 2026-06-27 00:05 UTC &middot; two-stage workflow (transcript, then translations)</sub>
         """
     )
 
@@ -328,6 +343,7 @@ with gr.Blocks(title="EchoScript") as demo:
                 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(
@@ -341,37 +357,15 @@ with gr.Blocks(title="EchoScript") as demo:
                 ),
             )
 
-            outputs_input = gr.CheckboxGroup(
-                choices=_compute_output_choices(has_key=False, exclude_code=None),
-                value=DEFAULT_OUTPUTS,
-                label="Outputs",
-            )
-
-            api_key_input.input(
-                fn=_on_key_or_source_change,
-                inputs=[api_key_input, language_input, outputs_input],
-                outputs=[outputs_input],
-            )
-            api_key_input.change(
-                fn=_on_key_or_source_change,
-                inputs=[api_key_input, language_input, outputs_input],
-                outputs=[outputs_input],
-            )
-            language_input.change(
-                fn=_on_key_or_source_change,
-                inputs=[api_key_input, language_input, outputs_input],
-                outputs=[outputs_input],
-            )
-
-            process_button = gr.Button("Generate Outputs", variant="primary")
+            generate_transcript_button = gr.Button("Generate Transcript", variant="primary")
             reset_button = gr.Button("Reset (clear cache)", size="sm")
 
         with gr.Column(scale=2):
             gr.Markdown("### Results Dashboard")
-            dashboard_output = gr.Markdown("Upload an audio file and click **Generate Outputs** to begin.")
+            dashboard_output = gr.Markdown("Upload an audio file and click **Generate Transcript** to begin.")
 
             with gr.Tabs():
-                with gr.Tab("Transcript") as transcript_tab:
+                with gr.Tab("Transcript"):
                     transcript_box = gr.Textbox(
                         label="Transcript",
                         lines=16,
@@ -381,11 +375,15 @@ with gr.Blocks(title="EchoScript") as demo:
                     transcript_download = gr.DownloadButton("Download TXT")
 
                 with gr.Tab("Translations"):
-                    gr.Markdown(
-                        "Every language selected in **Outputs** appears below at "
-                        "once -- nothing is hidden behind a tab you have to click "
-                        "through."
+                    translations_placeholder = gr.Markdown(
+                        "Generate a transcript first to see the languages available to "
+                        "translate it into."
                     )
+                    with gr.Group(visible=False) as translations_picker_group:
+                        gr.Markdown("Translate to:")
+                        translate_choices_input = gr.CheckboxGroup(choices=[], value=[], label=None)
+                        generate_translations_button = gr.Button("Generate Translations", variant="primary")
+
                     translation_groups = {}
                     translation_boxes = {}
                     translation_downloads = {}
@@ -406,24 +404,29 @@ with gr.Blocks(title="EchoScript") as demo:
                 with gr.Tab("Subtitles"):
                     gr.Markdown(
                         "Subtitles are generated from the transcript "
-                        "(source language), so they stay in sync no matter "
-                        "which translations are also generated."
+                        "(source language) as soon as it's ready -- no "
+                        "translation needed."
                     )
                     with gr.Row():
                         srt_download = gr.DownloadButton("Download SRT")
                         vtt_download = gr.DownloadButton("Download VTT")
 
-    # Build the flat outputs list in the exact order process_audio() returns.
-    click_outputs = [
+    # Outputs shared by Stage 1 (Generate Transcript) and Reset.
+    transcript_stage_outputs = [
         dashboard_output,
         transcript_box,
         transcript_download,
-        transcript_tab,
-        outputs_input,
+        translate_choices_input,
+        translations_picker_group,
+        translations_placeholder,
     ]
     for label in _TRANSLATION_SECTION_ORDER:
-        click_outputs += [translation_groups[label], translation_boxes[label], translation_downloads[label]]
-    click_outputs += [
+        transcript_stage_outputs += [
+            translation_groups[label],
+            translation_boxes[label],
+            translation_downloads[label],
+        ]
+    transcript_stage_outputs += [
         srt_download,
         vtt_download,
         transcript_state,
@@ -431,23 +434,52 @@ with gr.Blocks(title="EchoScript") as demo:
         translations_state,
     ]
 
-    process_button.click(
-        fn=process_audio,
+    generate_transcript_button.click(
+        fn=generate_transcript,
         inputs=[
             audio_input,
             start_input,
             end_input,
             language_input,
-            outputs_input,
             api_key_input,
             transcript_state,
             signature_state,
             translations_state,
         ],
-        outputs=click_outputs,
+        outputs=transcript_stage_outputs,
+    )
+
+    # Outputs for Stage 2 (Generate Translations): just the per-language
+    # sections plus the translation cache.
+    translation_stage_outputs = []
+    for label in _TRANSLATION_SECTION_ORDER:
+        translation_stage_outputs += [
+            translation_groups[label],
+            translation_boxes[label],
+            translation_downloads[label],
+        ]
+    translation_stage_outputs += [translations_state]
+
+    generate_translations_button.click(
+        fn=generate_translations,
+        inputs=[translate_choices_input, api_key_input, transcript_state, translations_state],
+        outputs=translation_stage_outputs,
+    )
+
+    # Cascade the translate-to picker live as the key changes, once a
+    # transcript exists (no-op before that -- the picker isn't shown yet).
+    api_key_input.input(
+        fn=_on_api_key_change,
+        inputs=[api_key_input, transcript_state, translate_choices_input],
+        outputs=[translate_choices_input],
+    )
+    api_key_input.change(
+        fn=_on_api_key_change,
+        inputs=[api_key_input, transcript_state, translate_choices_input],
+        outputs=[translate_choices_input],
     )
 
-    reset_button.click(fn=reset_session_state, outputs=click_outputs)
+    reset_button.click(fn=reset_session_state, outputs=transcript_stage_outputs)
 
 if __name__ == "__main__":
     demo.launch()