Include local Gradio app and standalone installation guide

README.md

@@ -23,7 +23,7 @@ model-index:
 XML dialogue and two selectable voice templates. The output is a normalized
 24 kHz stereo WAV: **speaker A on the left, speaker B on the right**.
 
-[Try the interactive demo](https://huggingface.co/spaces/penguinfish1688/duplexdataengine-demo)
+The interactive app is included as `app.py`; see **Run the interactive demo** below.
 
 This repository contains a standalone Stage III inference release: merged
 model weights, the deterministic XML interleaver, the audio codec, voice
@@ -72,6 +72,21 @@ the shorter finished lane is zero-padded. CPU execution is available through
 `--device cpu`, but is much slower. Hardware and timing verification are in
 `verification.json` once the public download check is complete.
 
+## Run the interactive demo
+
+The downloadable Gradio app provides editable XML, independent voice selectors,
+reference previews, generation controls, and the two featured examples:
+
+```bash
+pip install -r requirements-demo.txt
+python app.py
+```
+
+Open the local URL printed by Gradio. A GPU is recommended. Set `DUDE_DEVICE=cpu`
+to use CPU inference, which is much slower. The same app can be deployed to a
+Hugging Face Gradio Space with appropriate hosting access. Hosting availability
+does not affect public downloads or local inference.
+
 ## How to write the XML
 
 Use `<A>` and `<B>` for the two speakers. Exactly **one turn has no `start`**:

app.py

@@ -0,0 +1,132 @@
+"""Public DuDE demo; model/code/assets are independent of the research repo."""
+import spaces  # Enable ZeroGPU before importing torch.
+import json
+import os
+from pathlib import Path
+import tempfile
+
+import gradio as gr
+from huggingface_hub import snapshot_download
+
+from dude_tts import DuDE
+
+MODEL_ID = 'penguinfish1688/duplexdataengine'
+LOCAL = Path(os.environ.get('DUDE_MODEL_DIR', Path(__file__).resolve().parent))
+ROOT = LOCAL if (LOCAL/'release.json').is_file() else Path(
+    snapshot_download(MODEL_ID, revision=os.environ.get('DUDE_MODEL_REVISION')))
+EXAMPLES = json.loads((ROOT/'examples/examples.json').read_text())
+PRESETS = json.loads((ROOT/'voices/presets.json').read_text())
+CHOICES = [(value['label'], key) for key, value in PRESETS.items()]
+MODEL = DuDE.from_pretrained(ROOT, device=os.environ.get('DUDE_DEVICE', 'cuda'))
+
+
+@spaces.GPU(duration=120)
+def synthesize(xml, voice_a, voice_b, seed, max_seconds):
+    try:
+        result = MODEL.generate(xml, voice_a, voice_b, seed=int(seed), max_seconds=float(max_seconds))
+    except ValueError as error:
+        raise gr.Error(str(error)) from error
+    output = Path(tempfile.mkdtemp(prefix='dude-output-'))/'dialogue.wav'
+    result.save(output)
+    status = 'Both speakers emitted EOS.' if all(result.eos) else (
+        'The safety limit was reached before both speakers finished. Increase it or shorten the dialogue.')
+    return str(output), str(output), status
+
+
+def preset_preview(voice):
+    return str(ROOT/PRESETS[voice]['preview'])
+
+
+def load_example(index):
+    example = EXAMPLES[index]
+    return ((ROOT/example['xml']).read_text(), example['voice_a'], example['voice_b'],
+            example['seed'], example['max_seconds'])
+
+
+XML_GUIDE = '''
+### Write a two-speaker dialogue
+
+Use `<A>` and `<B>` for speakers. Exactly one turn has **no `start`**: the root.
+Every later turn references an inline anchor with `start="e1"`. Define each
+anchor once as `<e1/>`, `<e2/>`, etc. The `<duplex>` wrapper is optional.
+
+**Turn-taking:** put the anchor at the preceding turn's end.
+```xml
+<duplex>
+  <A>Hello! How was your day?<e1/></A>
+  <B start="e1">Pretty good. I finished the project.<e2/></B>
+  <A start="e2">That's great! <laugh/></A>
+</duplex>
+```
+
+**Overlap:** put the anchor inside a turn so the other speaker enters there.
+```xml
+<duplex>
+  <A>I walked to the park, <e1/>and then stopped for coffee.<e2/></A>
+  <B start="e1">Mm-hmm.</B>
+  <B start="e2">That sounds nice.</B>
+</duplex>
+```
+
+Anchors indicate text dependencies, not timestamps. Exact timing is learned and
+can vary. Same-speaker collisions are serialized in XML order. Available events:
+`<laugh/>`, `<cough/>`, `<breath/>`, `<sigh/>`, `<cry/>`, `<sneeze/>`, `<gasp/>`.
+Write spoken backchannels as ordinary text. Escape literal `&` as `&amp;`.
+Do not add `type`, timestamp, or duration attributes. Each anchor must be unique
+and all `start` references must exist. Cycles and multiple roots are rejected.
+'''
+
+
+with gr.Blocks(title='DuDE — Duplex Speech', delete_cache=(3600, 3600)) as demo:
+    gr.Markdown('''# Two voices. One conversation.
+**DuDE by Cheng-Kuang Chang** turns an XML dialogue into synchronized stereo speech.
+Choose one voice for each speaker. **A plays on the left; B on the right.**
+[Download the model and inference code](https://huggingface.co/penguinfish1688/duplexdataengine)
+''')
+    with gr.Accordion('How to write the XML', open=True):
+        gr.Markdown(XML_GUIDE)
+    initial = load_example(0)
+    xml = gr.Code(value=initial[0], language='html', label='Dialogue XML', lines=15)
+    with gr.Row():
+        voice_a = gr.Dropdown(CHOICES, value=initial[1], label='Speaker A — left')
+        voice_b = gr.Dropdown(CHOICES, value=initial[2], label='Speaker B — right')
+    with gr.Row():
+        preview_a = gr.Audio(value=preset_preview(initial[1]), label='Voice A reference', interactive=False)
+        preview_b = gr.Audio(value=preset_preview(initial[2]), label='Voice B reference', interactive=False)
+    voice_a.change(preset_preview, voice_a, preview_a, queue=False)
+    voice_b.change(preset_preview, voice_b, preview_b, queue=False)
+    with gr.Accordion('Generation settings', open=False):
+        seed = gr.Number(value=initial[3], precision=0, label='Random seed')
+        maximum = gr.Slider(10, 180, value=initial[4], step=1, label='Audio safety limit (seconds; not target duration)')
+    generate = gr.Button('Generate stereo speech', variant='primary')
+    output = gr.Audio(type='filepath', label='Generated conversation', interactive=False)
+    download = gr.File(label='Download stereo WAV')
+    status = gr.Textbox(label='Generation status', interactive=False)
+    generate.click(synthesize, [xml, voice_a, voice_b, seed, maximum], [output, download, status],
+                   api_name='generate', concurrency_limit=1)
+    gr.Markdown('## Listen to the featured examples\nThese are the original checkpoint-8565 outputs.')
+    for index, example in enumerate(EXAMPLES):
+        gr.Markdown(f'### {example["id"]}-student')
+        gr.Audio(value=str(ROOT/example['audio']), label='Normalized stereo example', interactive=False)
+        with gr.Accordion('Show complete input XML', open=False):
+            gr.Code(value=(ROOT/example['xml']).read_text(), language='html', interactive=False)
+        gr.Button('Use this example').click(lambda i=index: load_example(i), outputs=[xml, voice_a, voice_b, seed, maximum], queue=False)
+    gr.Markdown('''### Notes and citation
+English is the evaluated language. Words, pauses, vocal events, and overlaps can be imperfect.
+Ten held-out conversations all emitted EOS on both lanes; automated WER was 15.70%,
+but the timing check did not pass. See the model card for the full evaluation.
+Model and reference assets are for noncommercial use under CC BY-NC 4.0.
+References: Qwen3-TTS and Meta Seamless Interaction.
+
+```bibtex
+@misc{chang2026dude,
+  author = {Cheng-Kuang Chang},
+  title = {DuDE: XML-conditioned Duplex Text-to-Speech},
+  year = {2026},
+  url = {https://huggingface.co/penguinfish1688/duplexdataengine}
+}
+```
+''')
+
+if __name__ == '__main__':
+    demo.queue(max_size=20).launch()

requirements-demo.txt

@@ -0,0 +1,3 @@
+-r requirements.txt
+gradio==6.17.3
+spaces