BoltzmannEntropy/MimikaStudio 是一个托管在 GitHub 上的开源项目，主要使用 Dart 编写，采用 GNU General Public License v3.0 许可证，目前获得 751 个 Star、102 次 Fork。
仓库全名
BoltzmannEntropy/MimikaStudio
开源许可证
GNU General Public License v3.0
Star 数
751
Fork 数
102
未关闭 Issue
3
README 摘要
v2026.04.1 macOS (Apple Silicon) · MLX Native Clone any voice in seconds + Agentic Voice Cloning Server Local-first voice cloning, text-to-speech, Read Aloud document reader, audiobook creator, and an agentic voice cloning server with state-of-the-art job queue orchestration. Optimized for Apple Silicon with native Metal acceleration via MLX. Get Started · View on…
Clone any voice in seconds + Agentic Voice Cloning Server
Local-first voice cloning, text-to-speech, Read Aloud document reader, audiobook creator, and an agentic voice cloning server with state-of-the-art job queue orchestration. Optimized for Apple Silicon with native Metal acceleration via MLX.
Custom Voice Cloning | Text-to-Speech | PDF Read Aloud | Audiobook Creator | MCP & API Dashboard
A local-first application for macOS (Apple Silicon) with four integrated capabilities and production-oriented workflows: clone any voice from as little as 3 seconds of reference audio using multiple engines (Qwen3-TTS and Chatterbox), generate high-quality text-to-speech with fast and expressive model families (Kokoro and Supertonic), read documents aloud with sentence-level highlighting and synchronized progression (PDF, DOCX, EPUB, Markdown, TXT), and convert full documents to audiobooks with queueable chapter generation and reusable voice presets. MimikaStudio also operates as an agentic voice cloning server with a state-of-the-art jobs queue for TTS, cloning, and audiobook pipelines. It runs fully on-device, includes first-run model download management, and exposes both UI and API paths for advanced local automation.
License: Source code is licensed under Business Source License 1.1 (BSL-1.1), and binary distributions are licensed under the MimikaStudio Binary Distribution License. See LICENSE, BINARY-LICENSE.txt, and the website License page.
Note: Windows support is planned for a future release.
Latest Release
v2026.04.1 adds in-app PDF page preview for audiobook source documents, disables the old 7-day expiration and Polar/LemonSqueezy purchase flow in the Pro UI, and removes pricing/buying paths from the website in favor of direct GitHub release downloads.
Full “A Scandal in Bohemia” audiobook chapters generated with Qwen3-TTS voice cloning. These are the primary long-form Qwen demos bundled with the repo.
MimikaStudio also ships with 8 custom-designed reference voices for local cloning workflows: Alistair, Anastasia, Beatrice, Eleanor, Harriet, Mikhail, Svetlana, and Yelena.
Full audiobook excerpts generated with Kokoro TTS from Marcus Aurelius’ “Meditations” (public domain). The source excerpt is normalized before generation to avoid broken mid-word line-wrap artifacts. Generated at 0.95x speed for natural pacing.
Long-form audiobook demo (George, British male, Marcus Aurelius excerpt, 0.95x speed)
Kokoro short examples are bundled under backend/data/samples/kokoro/. Long-form audiobook demos are in backend/data/pregenerated/audiobooks/, and short engine-specific demos are grouped under backend/data/pregenerated/qwen3/, backend/data/pregenerated/chatterbox/, backend/data/pregenerated/cosyvoice3/, and backend/data/pregenerated/supertonic/.
Installation
System Requirements
Component
Requirement
OS
macOS 13+ (Ventura or later)
Chip
Apple Silicon (M1/M2/M3/M4) — Intel not supported
RAM
8GB minimum, 16GB+ recommended
Storage
5-10GB for models
Python
3.10 or later
Flutter
3.x with desktop support
Windows & Linux: The codebase supports these platforms, but pre-built binaries are currently macOS-only. Windows/Linux support is planned for future releases.
Unsigned DMG (Apple Gatekeeper)
As of April 1, 2026, the MimikaStudio DMG is not yet signed/notarized by Apple.
macOS may block first launch until you explicitly allow it in security settings.
Open the DMG and drag MimikaStudio.app to /Applications.
Remove the quarantine attribute by running one of these commands in Terminal:
# If installed to /Applications (system-wide):
xattr -d com.apple.quarantine /Applications/MimikaStudio.app
# If installed to ~/Applications (user-only):
xattr -d com.apple.quarantine ~/Applications/MimikaStudio.app
Why is this required? macOS quarantines all downloaded apps. For unsigned apps, Gatekeeper may block execution entirely. The xattr -d com.apple.quarantine command removes this flag, allowing the app to run.
In Applications, right-click MimikaStudio.app and select Open.
Click Open in the warning dialog.
If macOS still blocks launch, go to:
System Settings -> Privacy & Security -> Open Anyway (for MimikaStudio), then confirm with password/Touch ID.
On first launch, wait for the bundled backend to start. The startup log screen below is expected for a few seconds.
On first use, click Download for the required model in the in-app model card.
Automated Install (Recommended)
A single install.sh in the project root handles everything: prerequisites,
virtual environment, all Python dependencies (including Qwen3-TTS, Chatterbox,
OmegaConf, Perth, etc.), database setup, and Flutter.
git clone https://github.com/BoltzmannEntropy/MimikaStudio.git
cd MimikaStudio
./install.sh
The script will:
Check / install Homebrew, Python 3, espeak-ng, and ffmpeg
Create a Python venv in the project root (./venv)
Install all Python dependencies from the root requirements.txt
Install chatterbox-tts with --no-deps (its runtime deps are already in requirements.txt)
Download the Dicta ONNX Hebrew diacritizer model (~1.1 GB) for Chatterbox Hebrew TTS (skip with SKIP_DICTA=1)
Verify that every critical import works
Initialize the SQLite database
Set up Flutter (if installed)
Note: ./install.sh creates the Python virtual environment and installs large dependencies, so the first run can take a few minutes.
The Dicta ONNX Hebrew diacritizer (~1.1 GB) is downloaded by install.sh automatically. If you skipped it (SKIP_DICTA=1) and need Hebrew TTS later, run:
# Start all services (Backend + MCP + Desktop UI)
./bin/mimikactl up
# Or: Backend + MCP only (no Flutter UI)
./bin/mimikactl up --no-flutter
# Check status
./bin/mimikactl status
# View logs
./bin/mimikactl logs backend
Example startup output:
=== Starting MimikaStudio ===
Starting backend...
Waiting for http://localhost:8000/api/health ...... OK
Starting MCP Server...
MCP Server started on port 8010
Starting Flutter UI (dev mode)...
Platforms
MimikaStudio ships a desktop UI backed by the same local FastAPI agentic voice cloning server:
macOS Desktop App (default): ./bin/mimikactl up
Why MimikaStudio?
MimikaStudio brings together the latest advances in neural text-to-speech into a unified desktop experience.
Lightning-Fast British TTS with Kokoro
Kokoro TTS delivers sub-200ms latency with crystal-clear British and American accents. The 82M parameter model runs effortlessly on any machine, generating natural-sounding speech with Emma, George, Lily, and other premium voices.
Voice Cloning Without Limits
Clone any voice from remarkably short audio samples. Qwen3-TTS requires just 3 seconds of reference audio to capture a speaker’s characteristics. Upload a voice memo, a podcast clip, or any audio snippet, and MimikaStudio will synthesize new speech in that voice.
For multilingual cloning, Chatterbox Multilingual TTS supports 23 languages. Both Qwen3 and Chatterbox share a unified voice library — upload a voice sample once and use it across all cloning engines.
Premium Preset Speakers
MimikaStudio includes 9 premium preset speakers across 4 languages (English, Chinese, Japanese, Korean), each with distinct personalities. These CustomVoice speakers require no audio samples at all.
Read Aloud Document Reader: Read PDF, DOCX, EPUB, Markdown, and TXT aloud with sentence-by-sentence highlighting
Audiobook Creator: Convert documents into WAV/MP3/M4B audiobooks with smart chunking, crossfade merging, progress tracking, and chapter markers (Kokoro voices only)
State-of-the-Art Unified Jobs Queue: Track, schedule, and monitor every executed job (TTS, voice clone, and audiobook) with queue state, progress, and inline playback controls
Shared Voice Library: Voice samples shared across all cloning engines (Qwen3, Chatterbox)
Model Manager: In-app model download manager — check status and download models on demand
Model Size Selection: 0.6B (Fast) or 1.7B (Quality)
Kokoro TTS: Fast, high-quality English synthesis with 21 British/American voices (IPA transcription is not part of the current release)
Default Voice Samples: Mikhail, Yelena, Anastasia, and Svetlana ship with the app; user uploads are stored in ~/MimikaStudio/data/user_voices/cloners/ by default (or MIMIKA_DATA_DIR)
User Voices in UI: Uploaded voices appear immediately under each engine’s Your Voices section
Jobs Tab: State-of-the-art unified queue of TTS, voice clone, and audiobook jobs with live progress, completion state, and playback controls
Folder View in Settings: View and open user home, Mimika data, logs, default voices (Yelena/Svetlana), and user clone voices folders directly from the app
Voice Previews: Tap play/pause/stop to audition voices before generating
Document Reader: Read PDFs, TXT, and MD files aloud with Kokoro TTS
Audiobook Creator: Convert full documents to audiobook files (WAV/MP3/M4B) with smart chunking, crossfade merging, progress tracking, and playback controls (Kokoro voices only)
CLI Tool: Full command-line interface for Kokoro and Qwen3
MCP & API Dashboard: Built-in tab showing all MCP tools and REST endpoints with live server status
Settings Workspace: General, MCP, Pro, and About are grouped under Settings sub-tabs
MCP Server: Full MCP integration for programmatic access to all API endpoints
Windows Installer: PyInstaller + Inno Setup build script for standalone Windows distribution
60+ REST API endpoints with FastAPI (auto-documented at /docs)
Voice Prompts Workflow
The Voice Prompts tab is the shared library for voice cloning. Add a voice once and reuse it across Qwen3 Clone and Chatterbox flows without re-uploading the sample for each engine.
Search, filter, preview, edit, and delete saved prompts from one library
Default voices ship with the app, and uploaded prompts appear immediately in clone screens
The same prompt metadata is reused across local clone engines
Clone from YouTube
MimikaStudio can turn a YouTube clip into a reusable voice prompt without leaving the app:
Open Voice Prompts > Import URL
Paste a YouTube URL and optionally set a start time
Download a 20-second preview and listen to it locally
Save the preview as a named voice prompt with optional transcript, gender, and language metadata
Use that saved prompt from the clone screens just like any uploaded reference voice
Control Script (mimikactl)
# Service Commands
./bin/mimikactl up # Start all services
./bin/mimikactl up --no-flutter # Backend + MCP only
./bin/mimikactl down # Stop all services
./bin/mimikactl restart # Restart all
./bin/mimikactl status # Check status
# Backend Commands
./bin/mimikactl backend start # Start backend only
./bin/mimikactl backend stop # Stop backend
# Flutter Commands
./bin/mimikactl flutter start # Start Flutter (release mode)
./bin/mimikactl flutter start --dev # Start in dev mode
./bin/mimikactl flutter stop # Stop Flutter
./bin/mimikactl flutter build # Build macOS app
# MCP Server Commands
./bin/mimikactl mcp start # Start MCP server (port 8010)
./bin/mimikactl mcp stop # Stop MCP server
./bin/mimikactl mcp status # Check MCP status
# Utility Commands
./bin/mimikactl logs [service] # Tail logs (backend|mcp|flutter|all)
./bin/mimikactl test # Run API tests
./bin/mimikactl clean # Clean logs and temp files
./bin/mimikactl version # Show version info
CLI Tool (mimika)
Full command-line interface for voice cloning and TTS generation.
Text string or file path (.txt, .pdf, .epub, .docx, .doc)
--voice
-v
bf_emma
Voice ID (see mimika voices --engine kokoro)
--speed
-s
1.0
Speech speed multiplier (0.5-2.0)
--output
-o
<input>.wav
Output WAV file path
Available Kokoro Voices:
Voice ID
Name
Gender
Accent
bf_emma
Emma
Female
British RP
bf_isabella
Isabella
Female
British
bf_alice
Alice
Female
British
bf_lily
Lily
Female
British
bm_george
George
Male
British
bm_lewis
Lewis
Male
British
bm_daniel
Daniel
Male
British
af_heart
Heart
Female
American
af_bella
Bella
Female
American
af_nicole
Nicole
Female
American
af_aoede
Aoede
Female
American
af_kore
Kore
Female
American
af_sarah
Sarah
Female
American
af_sky
Sky
Female
American
am_michael
Michael
Male
American
am_adam
Adam
Male
American
am_echo
Echo
Male
American
am_liam
Liam
Male
American
am_onyx
Onyx
Male
American
am_puck
Puck
Male
American
am_santa
Santa
Male
American
mimika qwen3 - Voice Clone & Custom Voice
./bin/mimika qwen3 <input> [options]
Common Parameters:
Parameter
Short
Default
Description
input
required
Text string or file path (.txt, .pdf, .epub, .docx, .doc)
--output
-o
<input>.wav
Output WAV file path
--model
-m
1.7B
Model size: 0.6B (fast) or 1.7B (quality)
--language
-l
auto
Language code (auto, en, zh, ja, ko, de, fr, ru, pt, es, it)
--temperature
0.9
Generation randomness (0.1-2.0)
--top-p
0.9
Nucleus sampling threshold (0.1-1.0)
--top-k
50
Top-k sampling (1-100)
Custom Voice Mode (Preset Speakers):
Parameter
Short
Default
Description
--speaker
Ryan
Preset speaker name
--style
see below
Style instruction for voice
Default style: "Optimized for engaging, professional audiobook narration"
Available Preset Speakers:
Speaker
Language
Character
Ryan
English
Dynamic male, strong rhythm
Aiden
English
Sunny American male
Vivian
Chinese
Bright young female
Serena
Chinese
Warm gentle female
Uncle_Fu
Chinese
Seasoned male, mellow timbre
Dylan
Chinese
Beijing youthful male
Eric
Chinese
Sichuan lively male
Ono_Anna
Japanese
Playful female
Sohee
Korean
Warm emotional female
Voice Clone Mode:
Parameter
Short
Default
Description
--clone
flag
Enable voice cloning mode
--reference
-r
required
Reference audio file (WAV, 3+ seconds)
--reference-text
optional
Transcript of reference audio (improves quality)
mimika voices - List Available Voices
./bin/mimika voices [--engine kokoro|qwen3]
Supported File Formats
Format
Extension
Requirements
Plain Text
.txt
Built-in
PDF
.pdf
PyPDF2, pymupdf
EPUB
.epub
ebooklib, beautifulsoup4
Word Document
.docx
python-docx
Legacy Word
.doc
docx2txt
Markdown
.md
Built-in
All format dependencies are included in requirements.txt.
TTS Engines
Kokoro TTS
Fast, high-quality British English synthesis (82M parameters, 24kHz). Features 8 premium British voices including Emma, Alice, Isabella, Lily, George, Daniel, Fable, and Lewis.
Qwen3-TTS
Voice Clone Mode (Base)
Clone any voice from just 3+ seconds of reference audio.
MimikaStudio ships these 8 custom-designed clone voices for local Qwen3 prompting and demos: Alistair, Anastasia, Beatrice, Eleanor, Harriet, Mikhail, Svetlana, and Yelena.
Supported Language Showcase: Genesis 1:1 generated with the shipped Mimika voices across every Qwen3 clone language. Korean is included with Eleanor.
Language
Voice
Transcript
Sample
English
Alistair
In the beginning God created the heaven and the earth.
Use 9 premium preset speakers without any reference audio.
Models:
Qwen3-TTS-12Hz-0.6B-CustomVoice
Qwen3-TTS-12Hz-1.7B-CustomVoice
Style Instructions: Control tone with prompts like “Speak slowly”, “Very happy”, “Whisper”, or use “Optimized for engaging, professional audiobook narration” for long-form content.
Advanced Parameters
Parameter
Default
Range
Description
Temperature
0.9
0.1-2.0
Randomness in generation
Top P
0.9
0.1-1.0
Nucleus sampling threshold
Top K
50
1-100
Top-k sampling
Repetition Penalty
1.0
1.0-2.0
Reduce repetition
Seed
-1
-1 or 0+
Reproducible generation (-1=random)
Chatterbox Multilingual TTS
Chatterbox adds multilingual voice cloning from a reference audio prompt. It uses the same voice library flow as Qwen3 (default samples + your uploads).
23 Supported Languages:
Code
Language
Code
Language
Code
Language
ar
Arabic
he
Hebrew
no
Norwegian
da
Danish
hi
Hindi
pl
Polish
de
German
it
Italian
pt
Portuguese
el
Greek
ja
Japanese
ru
Russian
en
English
ko
Korean
sv
Swedish
es
Spanish
ms
Malay
sw
Swahili
fi
Finnish
nl
Dutch
tr
Turkish
fr
French
zh
Chinese
Parameters:
Temperature (randomness)
CFG weight (conditioning strength)
Exaggeration (style intensity)
Seed (reproducibility)
Hebrew TTS: Chatterbox Hebrew requires the Dicta ONNX diacritizer model (dicta-1.0.onnx, ~1.1 GB) which adds vowel marks (nikud) to unvocalized Hebrew text before synthesis. Without it, Hebrew output quality is severely degraded. The model can be downloaded from the app’s Model Manager, or automatically by install.sh (skip with SKIP_DICTA=1), and is stored at backend/models/dicta-onnx/dicta-1.0.onnx. To download manually:
MimikaStudio includes a full MCP (Model Context Protocol) server that exposes every API endpoint as MCP tools for programmatic access via Claude Code CLI, Codex, or any MCP-compatible client.
# 3) Start audiobook generation from a local PDF file
curl -s http://127.0.0.1:8010 \
-H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"audiobook_generate_from_file","arguments":{"file_path":"/absolute/path/to/document.pdf","title":"My Oral Exam Notes","voice":"bf_emma","speed":1.0,"output_format":"mp3"}}}'
# 4) Poll status until "completed"
curl -s http://127.0.0.1:8010 \
-H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"audiobook_status","arguments":{"job_id":"<JOB_ID>"}}}'
On completion, the file is created locally in backend/outputs/:
backend/outputs/audiobook-<JOB_ID>.mp3
Served locally at http://localhost:7693/audio/audiobook-<JOB_ID>.mp3
Using Mimika MCP from Codex and Claude Code
If your client is connected to the Mimika MCP server (http://127.0.0.1:8010), you can ask it to run the exact same flow.
Codex prompt example
Use Mimika MCP tool audiobook_generate_from_file with:
file_path=/absolute/path/to/document.pdf
title=My Oral Exam Notes
voice=bf_emma
output_format=mp3
Then poll audiobook_status until completed and return job_id + audio_url.
Claude Code prompt example
Call Mimika MCP audiobook_generate_from_file for /absolute/path/to/document.pdf
with voice bf_emma and output_format mp3.
Track audiobook_status every 10 seconds and report final audio_url.
MCP & API Dashboard (In-App)
The Settings > MCP screen in the Flutter app provides a live dashboard showing:
Server status — Backend API (port 7693), MCP Server (port 8010), and API Docs availability with green/red indicators
All MCP tools grouped by category (System, Kokoro, Qwen3, Chatterbox, Audiobook, Voice Management, Models, Samples) with expandable parameter details
All 60+ REST API endpoints grouped by category with HTTP method badges (GET/POST/PUT/DELETE)
Search — Filter tools and endpoints by name, path, or description
The dashboard fetches MCP tools live from the MCP server via JSON-RPC, so it always reflects the current tool set.
Running Tests
source venv/bin/activate
cd backend
# Run all tests (fast, no model loading required)
pytest tests/ -v
# Run specific test file
pytest tests/test_all_endpoints.py -v
# Run with actual model tests (slow, requires models downloaded)
RUN_MODEL_TESTS=1 pytest tests/
评论