Home

🎙️ Audioticon — The Emoji-Directed Audiobook Engine & Studio

Transform plain text and ebooks into broadcast-grade, multi-voiced audiobooks and audio dramas with intuitive emoji directing syntax, sentence-level SHA-256 caching, and real EBU R128 / ACX compliance certification.

---

🌟 Overview

Audioticon is an open-source, high-performance audiobook directing engine and visual workstation written in Rust (MIT / Apache-2.0). It eliminates the steep learning curve of traditional Digital Audio Workstations (DAWs) like Audacity, Reaper, or Pro Tools by replacing complex automation curves, clip slicing, and plugin chains with declarative emoji directing markers embedded directly in your manuscript.

Whether you are an indie author preparing an EPUB/DOCX for Audible (ACX) or Storytel, a voice-over director casting multiple characters, or a publisher producing full-cast audio dramas with Foley SFX and human punch-in corrections, Audioticon lets you write, direct, rehearse, and master full-length audiobooks with sub-20ms cache turnaround.

📖 Rozdział 1: Przebudzenie 🛑

🎙️ Poranek nad Warszawą był wyjątkowo chłodny. ⏸️
Adam podszedł do okna i odebrał wibrujący aparat. 🔔

👩 📱 Cześć Adam, czy masz już te dokumenty z dwudziestego czwartego lutego? 🛑

👨 💥Jeszcze nie! — krzyknął, po czym zniżył ton. — 🤫 Szukam ich w archiwum... 😮‍💨

---

📑 Wiki Navigation

• Audioticon Complete Manual
• Emoji Directing Grammar & Foley SFX
• 4 Neural TTS Engines (Offline & BYOK Cloud)
• VoiceLab, Human Punch-In & Voice Design
• Broadcast Mastering & Audio Ledger ACX Certification
• CLI Commands & Workflows
• Configuration File (audioticon.toml)
• Architecture & Engine Internals

---

🚀 Key Features

• 🎭 Emoji-Driven Directing & 3 Production Styles: Direct pacing, emotions, whispers, shouts, phone filters, cathedral reverbs, Foley SFX, and ambient soundscapes using inline emojis. Switch effortlesly between --style narrator, --style multi-voice, and --style audio-drama.
• 🤖 4 Neural TTS Engines:
  • Piper Neural TTS (--provider piper, 100% Offline): Persistent ONNX worker in RAM supporting Polish CC0 voices (pl_PL-darkman-medium, pl_PL-gosia-medium, pl_PL-mc_speech-medium) and 140+ multilingual voices.
  • Kokoro-82M ONNX (--provider kokoro, 100% Offline): Open-weight Apache-2.0 82M-parameter model (kokoro-v1.0.int8.onnx + voices-v1.0.bin) for en-us, en-gb, es, fr, it, pt-br (af_bella, am_adam, bf_emma, bm_george).
  • Microsoft Edge Neural TTS (--provider edge): Fast 6-stream concurrent synthesis (pl-PL-MarekNeural, pl-PL-ZofiaNeural).
  • ElevenLabs v3 (--provider elevenlabs, BYOK): Bring-Your-Own-Key cloud integration with expressive tag translation ([whispers], [sighs], [shouts]) and pre-render cost estimation (--estimate).
• ⚡ Sentence-Level SHA-256 Cache & Crash-Resume: Every sentence is fingerprinted (compute_segment_hash) by text, voice, prosody, and DSP filter. Editing one comma in a 10-hour book re-renders only that single sentence, streaming the rest from disk with 5ms sin/cos equal-power crossfades in ~20 ms.
• 🎚️ Real EBU R128 Mastering & Audio Ledger Certificate: Masters audio to -19.5 LUFS and True Peak <= -3.0 dBFS with warm studio room tone (-68 dBFS), then physically measures the output file via ffmpeg -af loudnorm=print_format=json to issue a signed .certificate.json for Audible (ACX) and Storytel.
• 📦 Apple M4B, 24-bit Studio Master FLAC & MP3 Export: Native chapter markers (ffmetadata) and +faststart atom placement.
• 🎙️ VoiceLab & Human Punch-In: Analyze microphone recordings for SNR, RMS, Peak, and clipping; record human voice punch-ins (audioticon voicelab punch-in) for any sentence hash; export LJSpeech / XTTS (.zip) datasets.
• 📚 EPUB/DOCX Importer & AI Auto-Director: Extract chapters from .epub and .docx (audioticon import) and automatically annotate plain text with emoji direction via local Ollama or Cloud LLMs (audioticon direct) with 100% word-integrity verification.
• 🇵🇱 Advanced Polish Verbalizer: Context-aware normalization for dates, times, inflected numbers, currencies, abbreviations, and Roman numerals.

---

📖 The Emoji Directing Grammar

1. Structural, Pauses & Respiratory Cadence

Emoji	Token Name	Meaning & Engine Behavior
📖	Chapter Marker	Defines a chapter boundary (📖 Chapter 1: Start 🛑). Generates native M4B, FLAC, and ID3v2 chapter tables.
🛑	Full Stop Pause	Inserts a 900 ms warm studio room-tone pause (-68 dBFS).
⏸️	Short Pause	Inserts a 400 ms clause pause.
😮‍💨	Lektor Breath	Procedural 380 ms vocal-tract breath (750 Hz pharynx & 1750 Hz oral formants). Can also be automated via --cadence.

2. Cadence, Pitch & Dynamics

Emoji	Effect	Engine Behavior
🐢	Slow Tempo	Slows speech rate (-18%) for solemn narration or hesitation.
🐇	Fast Tempo	Accelerates speech rate (+20%) for action and urgency.
📉 / 📈	Pitch Down / Up	Shifts fundamental pitch (-8 Hz / +8 Hz) via phase-accurate resampling.
💥word	Dynamic Emphasis	Single-word dynamic punch (+18% volume, -6% rate, +4 Hz pitch).
🤫	Whisper	Intimate subdued vocal filtering and dynamic reduction.

3. Acoustic Environments & Custom Presets (audioticon.toml)

Emoji	Preset Name	DSP Chain Implementation
📱	Telephone	Bandpass filter (350 Hz – 3,200 Hz) with subtle asymmetric overdrive.
📻	Radio / Walkie-Talkie	Narrow bandpass (500 Hz – 2,600 Hz), compressor, and customizable variants (📻:wojskowe).
📢	Megaphone	Horn resonance EQ and mid-band saturation.
🏛️	Cathedral / Hall	Multi-tap acoustic reflections (aecho) with reverb tail padding (🏛️:kaplica).
🏰	Dungeon / Vault	Dark chamber reflections with high-frequency damping.
💭	Inner Monologue	Warm close-mic intimacy with subtle spacious chorus.
🤖	Robot / Cyborg	Ring modulation and metallic pitch flattening.

4. Foley Sound Effects (SFX) & Ambient Tracks

• Point SFX: 🔔 (bell/phone chime), 📄 (paper rustle), 👣 (footsteps/ice crunch), 🚪 (door), ⚡ (thunder), 🔫 (gunshot), 💓 (heartbeat), 🕰️ (clock tick), 🥂 (glass), 💧 (water drop). Custom assets in ./sfx/ or ~/.local/share/audioticon/sfx/ are automatically loaded first!
• Background Ambience: 🌧️ (rain), 🌊 (ocean waves), ☕ (cafe chatter), 🌲 (forest wind), 🔥 (fireplace).

---

🤖 4 Neural TTS Engines (Offline & BYOK Cloud)

Provider Flag	Engine	Mode	License	Supported Languages
--provider piper	Piper Neural TTS	100% Offline (RAM worker)	MIT / CC0 voices	Polish (gosia, darkman, mc_speech) + 40+ languages
--provider kokoro	Kokoro-82M ONNX	100% Offline (ONNX worker)	Apache-2.0	en-us, en-gb, es, fr, it, pt-br
--provider edge	Microsoft Edge Neural	Cloud (Free stream)	Personal / Dev	Polish (pl-PL-MarekNeural, pl-PL-ZofiaNeural) + global
--provider elevenlabs	ElevenLabs v3	Cloud (BYOK API Key)	Commercial (User plan)	Multilingual v2/v3 + cloned voices

---

🎙️ VoiceLab, Human Punch-In & Voice Design

Audioticon includes a complete local voice engineering suite (crates/core/src/voicelab.rs):

1. Acoustic Quality Analyzer: Measures sample duration, RMS dBFS, Peak dBFS, Signal-to-Noise Ratio (SNR dB), and sample clipping with actionable microphone tips.
2. Human Punch-In (audioticon voicelab punch-in): Record or import a human voice replacement for any specific sentence SHA-256 hash (recorded_<hash>.wav). All subsequent renders automatically splice your human take into the audiobook with 5ms crossfades.
3. Dataset Exporter: One-command export to standard LJSpeech / XTTS ZIP archives (profile.json + metadata.csv + normalized WAVs).
4. Voice Design (audioticon voicelab design): Generate custom synthetic voices from natural-language prompts via ElevenLabs Voice Design API.

---

🎚️ Audio Mastering & Audio Ledger Certification

Every rendered audiobook passes through an automated mastering chain and physical verification:

[Sentence WAV Segments (44.1 kHz, 16-bit Mono)] + [Foley SFX & Room-Tone Pauses (-68 dBFS)]
          │
          ▼
[Streaming Disk Stitcher with 5ms Equal-Power sin/cos Crossfades + Ambient Mixing]
          │
          ▼
[FFmpeg EBU R128 Mastering (loudnorm=I=-19.5:TP=-3.0:LRA=11)]
          │
          ▼
[Container Export: Apple M4B (+faststart) | 24-bit Studio Master FLAC | MP3 ID3v2]
          │
          ▼
[Audio Ledger Physical Verification: measure_audio_loudness() -> .certificate.json]

• Audible (ACX) Standard: Integrated Loudness -23.0 to -18.5 LUFS, True Peak <= -3.0 dBFS, 44,100 Hz.
• Storytel (EBU R128) Standard: Integrated Loudness -21.0 to -19.0 LUFS, True Peak <= -1.0 dBFS, 44,100 Hz / 48,000 Hz.

---

💻 Command Line Interface (CLI)

# 1. Render to Apple M4B, 24-bit FLAC, or MP3
audioticon render -i book.epub -o audiobook.m4b --provider piper --voice gosia
audioticon render -i script.txt -o master.flac --bit-depth 24 --style audio-drama --cadence
audioticon render -i book_en.txt --lang en --provider kokoro --voice af_bella -o book_en.m4b

# 2. Pre-render Cost & Cache Hit Estimator
audioticon estimate -i book.epub --provider elevenlabs

# 3. Import Ebooks & Auto-Direct with AI (Ollama / Cloud LLM)
audioticon import -i book.epub -o script.txt --chapters-dir ./chapters
audioticon direct -i raw.txt -o directed.txt --provider ollama --model Bielik-11B-v2.3-Instruct

# 4. Model Manager & Safe-Harbor Model Hub
audioticon models list --lang pl
audioticon models hub
audioticon models download gosia
audioticon models download kokoro-82m-int8

# 5. VoiceLab & Human Punch-In
audioticon voicelab create --name "Narrator" --gender male --lang pl --sample take1.wav
audioticon voicelab punch-in --id narrator --hash 4309872b --audio fix_sentence.wav
audioticon voicelab export narrator -o narrator_dataset.zip

# 6. Launch Modular Web Studio Workbench
audioticon studio

---

⚙️ Configuration (audioticon.toml)

Place an audioticon.toml file in your project directory to configure book metadata and custom DSP filter presets:

[project]
title = "Sygnał z Północy"
author = "Jarosław Kuchta"
narrator = "Darkman"
year = "2026"

[presets."radio:wojskowe"]
base_effect = "radio"
intensity = 1.0
distortion = 0.5
bandwidth = 0.6
volume = 1.15

[presets."🏛️:kaplica"]
base_effect = "cathedral"
reverb_decay = 0.35
distance = 0.4
volume = 1.0

---

🏗️ Project Architecture

audioticon/
├── crates/
│   ├── core/                     # Core Rust library (audioticon-core)
│   │   └── src/
│   │       ├── audio.rs          # Render engine, Piper/Edge/ElevenLabs bridges, 5ms crossfade, M4B/FLAC/MP3 export
│   │       ├── kokoro.rs         # Kokoro-82M ONNX bridge (kokoro_worker.py) + 24kHz -> 44.1kHz resampling
│   │       ├── parser.rs         # Emoji grammar parser & production style filtering
│   │       ├── normalizer.rs     # Polish Verbalizer (numbers, dates, times, currencies, abbreviations)
│   │       ├── cadence.rs        # Respiratory cadence & breath pause modeling
│   │       ├── presets.rs        # Parametric DSP filter chain generator & audioticon.toml loader
│   │       ├── sfx.rs            # Foley SFX asset resolver & procedural acoustic synthesizer
│   │       ├── cache.rs          # SHA-256 sentence fingerprinting & LRU cache pruning
│   │       ├── import.rs         # EPUB & DOCX chapter extractor
│   │       ├── autodirect.rs     # AI Auto-Director (Ollama / LLM) with word-integrity verification
│   │       ├── voicelab.rs       # Voice profiles, SNR/RMS/Peak analyzer, human Punch-In, LJSpeech ZIP export
│   │       ├── voice_design.rs   # Text-to-Voice prompt designer
│   │       ├── models.rs         # Offline model downloader (Piper voices.json + Model Hub)
│   │       ├── model_hub.rs      # Safe-Harbor model catalog & HMAC-signed EULA receipts
│   │       ├── ledger.rs         # Real EBU R128 LUFS / True-Peak measurement & cryptographic ACX certificate
│   │       ├── estimator.rs      # Pre-render duration, cache hit & API cost calculator
│   │       ├── credentials.rs    # Secure BYOK API key store (0600 permissions)
│   │       └── wallet.rs         # Studio license & HMAC-SHA256 voucher manager
│   └── cli/                      # CLI binary & Modular Studio HTTP server
├── docs/                         # Modular Studio Workbench (studio.html) & Classic Playground (index.html)
└── Cargo.toml                    # Workspace manifest

---

🤝 Contributing & License

• Codebase License: Dual-licensed under MIT License and Apache License 2.0.
• Third-Party Notices: See THIRD_PARTY_NOTICES.md.

---

Authored by Jarosław Kuchta (jarohull-ai).