🎙️ EchoForge

AI-Powered Radio Drama Production Studio

Turn a story idea into a fully-produced, voice-acted radio drama — automatically.

English · 简体中文 · 日本語

---

📸 Preview

Settings & Providers	Music & SFX Library

Agent Workbench	Live Progress

---

✨ What is EchoForge?

EchoForge is a local-first desktop studio that produces complete radio dramas (audio dramas) from a script or even just a story idea:

Story idea ──▶ LLM writes the script ──▶ TTS voices every character
                    │                            │
                    ├── 🎵 Adaptive BGM (intro ➝ ducking under speech ➝ outro)
                    ├── 🔊 Sound effects punctuating the dialogue
                    ├── 🎵 Instrumental interludes with timed duration
                    └── 🎬 Ending credits theme with fade-out
                                 ▼
                    Final MP3 / WAV export

It requires no audio-editing skills — write (or let the AI write) a script in a simple text format, and EchoForge handles casting, performance, music and mixing.

🌟 Key Features

🎭 Voice & Casting

• Three TTS providers — Fish Audio (cloned voices, 4 models) · MiniMax (Coding Plan sk-cp keys work! 13 built-in voices) · Microsoft Edge TTS (free, no key, 63 zh/en/ja voices)
• Voice transformation (DSP) — make ONE voice play MANY characters: 12 presets (Boy / Elder / Elf / Robot…) + manual pitch (±12 semitones, WSOLA time-preserving), formant shift, brightness, breathiness, roughness
• SSML pronunciation control — <break time="500ms"/> works across ALL providers (native on Microsoft, auto-converted elsewhere); emotion markers [softly] (S2) / (softly) (S1)
• Per-character voice binding with volume / speed / dB fine-tuning and character profiles
• Voice preview per voice-model and per role
• Content-hash caching — successful segments are never billed twice

🎵 Music Engine

• BGM with adaptive ducking: each dialogue block is wrapped in [intro ➝ speech(BGM ducks to 25%) ➝ outro]
• Per-directive fade control: #BGM=Night Piano,3,8 sets 3s fade-in / 8s fade-out
• Instrumental interludes #MUSIC=track,12 — timed music-only segments (auto-loops if the track is shorter)
• Ending theme #END=track,20 with a long fade-out
• 5 built-in royalty-free BGM tracks (≥2 min each, mostly piano) + batch upload your own

🔊 Sound Effects

• 20 built-in programmatically-synthesized royalty-free SFX (thunder, doorbell, footsteps, page-flip, birds, campfire…)
• #SFX=thunder,1.2 — punctuate dialogue with volume control; independent SFX library with batch upload

🤖 AI Scriptwriting & Agent Mode

• Works with any OpenAI-compatible API (OpenRouter, DeepSeek, Kimi, Qwen, Doubao, Ollama…) and Anthropic Claude (auto-detected)
• One-click model discovery (⚡ fetches the full model list)
• Context-rich prompting — the full project state (characters + profiles + voice bindings + BGM/SFX libraries + emotion-marker style matching the selected TTS model) is injected into every generation
• Agent Workbench — fully automated series production:
  1. AI writes the prologue + Episode 1
  2. You give rounds of feedback → AI revises (round 2, 3, …)
  3. Generate next episode with full story continuity
  4. Apply to workbench → auto voice-binding → auto generation

🖥️ Studio UX

• Clean light UI with grouped navigation (Configure / Create / Produce)
• Live progress: percentage, stage pipeline (Ready ➝ Per-segment ➝ Mix ➝ Export ➝ Done), and a card showing exactly which line is being processed
• Segment timeline table — edit text, BGM, fades and durations inline; regenerate single segments
• RPM limiting + classified retries (429/503/network back-off, friendly Chinese/English errors for 401/402)
• Offline mock mode — rehearse the full mix with placeholder voices, zero API cost

💾 Downloads (all platforms)

Platform	File	How
🪟 Windows	EchoForge-vX-win-x64.exe	double-click
🐧 Linux	EchoForge-vX-x86_64.AppImage (or the raw binary)	chmod +x && ./EchoForge*
🍎 macOS	EchoForge-macOS-Linux-source-vX.zip	bash install-macos.sh → EchoForge.app
🤖 Android	EchoForge-Android-Termux-vX.zip	bash install-android.sh in Termux
📱 Any phone (PWA)	—	run EchoForge on any computer with --host 0.0.0.0, open http://pc-ip:8080 on the phone, Add to Home Screen

The macOS/Linux/Android packages contain identical source + one-click installers that create .app / launchers automatically. All three ship every feature — TTS providers, voice transform, SSML, i18n, Agent.

🚀 Quick Start

Option A — Ready-to-run EXE (recommended)

1. Download EchoForge-v2.0.0-win-x64.exe from Releases (~55 MB, single file)
2. Double-click — first launch self-extracts the runtime (3–10 s) and opens your browser at http://127.0.0.1:17860
3. Configure keys:
   • TTS: free API key from fish.audio (model s2.1-pro-free is free)
   • LLM (optional): any OpenRouter / DeepSeek / local Ollama key for AI scriptwriting
4. Try Agent Workbench → type a story idea → 🚀

SmartScreen note: the binary is unsigned — click More info ➝ Run anyway. Upgrades are automatic: launching a newer EXE cleanly replaces the running old service.

Option B — From source

git clone https://github.com/TechnologyStar/EchoForge.git
cd EchoForge
pip install -r requirements.txt
python app.py        # opens http://127.0.0.1:17860

Windows users can also double-click build.bat (needs Python 3.11–3.13) to produce their own single-file EXE via PyInstaller.

📖 Script Format

The whole drama is plain text:

// ===== Act 1 =====
#BGM=Rainy Night Piano,3,8        ← BGM with 3s fade-in / 8s fade-out
#SFX=doorbell                      ← punctuate with a sound effect
【Narrator】Late at night, the bell of the old bookstore rang.
Store owner: "This late… a customer?"
#MUSIC=Suspense Pulse,10          ← 10-second instrumental interlude
Girl: [softly] I'm looking for a book that never grows old.
#END=Moonlight Lullaby,18         ← ending theme, fades out

Directive	Meaning
【Role】line or Role: line	Dialogue (both forms, mixable)
#BGM=name[,fadein,fadeout]	Background music for subsequent lines
#BGM=none	Clear BGM
#SFX=name[,volume]	Sound effect insert (volume 0–1.5)
#MUSIC=name,seconds	Music-only interlude (timed)
#END=name,seconds	Ending theme (long fade-out)
// comment	Ignored line
[softly] / (softly)	Emotion markers — brackets for S2 models, parentheses for S1

Full specification: docs/script-format.md

🔧 Configuration Guides

• Getting Started — keys, first drama, FAQ
• LLM Providers — OpenRouter / DeepSeek / Kimi / Qwen / Doubao / Claude / Ollama
• Audio Engine — how ducking, fades and mixing work

📱 Android / macOS / Linux

• Android (Termux): pkg install python flask requests numpy soundfile lameenc, pip install edge-tts, then bash run-android.sh — serves on port 8080, open from any browser on the same Wi-Fi
• macOS / Linux: pip install -r requirements.txt && python app.py (identical to Windows source mode; --host 0.0.0.0 --port 8080 for LAN)

🛠️ Tech Stack

Layer	Choice
Backend	Python 3.11 · Flask · NumPy · soundfile · lameenc
Frontend	Vanilla JS · hand-rolled light-theme design system
TTS	Fish Audio REST (/v1/tts, model via header)
LLM	OpenAI-compatible + Anthropic native (auto-switch)
Packaging	Custom C launcher (static zlib self-extractor, launcher.c) · mingw-w64 cross-compiled

The single-file EXE layout: [C launcher | zlib payload | u64 length | magic] — the launcher version-checks a running service, performs automatic upgrades (kills the old service), and self-extracts the Python runtime on first run. No PyInstaller dependency for official builds.

🗺️ Roadmap

• UI localization (EN / ZH / JA switcher) ✨ v2.0
• SSML-level pronunciation control ✨ v2.0
• Multi-episode batch export with ID3 tags ✨ v2.0
• Waveform preview timeline ✨ v2.0
• macOS / Linux builds

🤝 Contributing

Issues and PRs are welcome! The audio synthesizers (bgm_synth.py, sfx_synth.py) are pure NumPy — new royalty-free BGM/SFX recipes are especially appreciated.

📄 License

MIT — the built-in BGM/SFX are programmatically synthesized and royalty-free.

---

⭐ If EchoForge saved you an afternoon of audio editing, consider starring the repo!

Made with 🎙️ and a lot of piano notes.