### Manual MimikaStudio Installation Steps

Source: https://github.com/boltzmannentropy/mimikastudio/blob/main/README.md

Follow these steps for a manual installation of MimikaStudio, including system dependencies, Python environment, and application setup.

```bash
git clone https://github.com/BoltzmannEntropy/MimikaStudio.git
cd MimikaStudio
```

```bash
# System dependencies (macOS)
brew install espeak-ng ffmpeg python@3.11
```

```bash
# Python venv
python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip
```

```bash
# All Python dependencies (from project root)
pip install -r requirements.txt
```

```bash
# Chatterbox TTS (--no-deps to avoid version conflicts with its strict pins)
pip install --no-deps chatterbox-tts==0.1.6
```

```bash
# Initialize database
cd backend && python3 database.py && cd ..
```

```bash
# Flutter (optional, for desktop app UI)
cd flutter_app && flutter pub get && cd ..
```

```bash
# Start
./bin/mimikactl up
```

--------------------------------

### Automated MimikaStudio Installation

Source: https://github.com/boltzmannentropy/mimikastudio/blob/main/README.md

Clone the repository and run the install script for an automated setup of MimikaStudio, including dependencies and environment configuration.

```bash
git clone https://github.com/BoltzmannEntropy/MimikaStudio.git
cd MimikaStudio
./install.sh
```

--------------------------------

### Start Backend Service with mimikactl

Source: https://github.com/boltzmannentropy/mimikastudio/blob/main/README.md

Starts only the Mimika Studio backend service.

```bash
./bin/mimikactl backend start
```

--------------------------------

### Start All Services with mimikactl

Source: https://github.com/boltzmannentropy/mimikastudio/blob/main/README.md

Use this command to start all Mimika Studio services. To start only the backend and MCP, use the --no-flutter flag.

```bash
./bin/mimikactl up
```

```bash
./bin/mimikactl up --no-flutter
```

--------------------------------

### MimikaStudio Quick Start Commands

Source: https://github.com/boltzmannentropy/mimikastudio/blob/main/README.md

Essential commands for starting, managing, and viewing logs for MimikaStudio services. Use `--no-flutter` to run without the desktop UI.

```bash
# Start all services (Backend + MCP + Desktop UI)
./bin/mimikactl up
```

```bash
# Or: Backend + MCP only (no Flutter UI)
./bin/mimikactl up --no-flutter
```

```bash
# Check status
./bin/mimikactl status
```

```bash
# View logs
./bin/mimikactl logs backend
```

--------------------------------

### Start MimikaStudio Services

Source: https://github.com/boltzmannentropy/mimikastudio/blob/main/README.md

Activate the Python virtual environment and use the mimikactl script to start the backend, MCP, and desktop application.

```bash
source venv/bin/activate
./bin/mimikactl up
```

--------------------------------

### MCP Server - Audiobook Generation Example

Source: https://github.com/boltzmannentropy/mimikastudio/blob/main/README.md

Example workflow for generating an audiobook using the MCP server.

```APIDOC
## MCP Tool: audiobook_generate_from_file

### Description
Initiates audiobook generation from a local file using the MCP server.

### Method
JSON-RPC Call

### Endpoint
http://127.0.0.1:8010

### Parameters
#### Method Parameters
- **name** (string) - Required - The name of the tool to call, which is "audiobook_generate_from_file".
- **arguments** (object) - Required - Contains the arguments for the tool.
  - **file_path** (string) - Required - The absolute path to the document file.
  - **title** (string) - Required - The title of the audiobook.
  - **voice** (string) - Required - The voice to use for narration (e.g., "bf_emma").
  - **speed** (number) - Optional - The narration speed, defaults to 1.0.
  - **output_format** (string) - Required - The desired output format (e.g., "mp3").

### Request Example
```json
{
  "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"
    }
  }
}
```
```

```APIDOC
## MCP Tool: audiobook_status

### Description
Polls the status of an audiobook generation job via the MCP server.

### Method
JSON-RPC Call

### Endpoint
http://127.0.0.1:8010

### Parameters
#### Method Parameters
- **name** (string) - Required - The name of the tool to call, which is "audiobook_status".
- **arguments** (object) - Required - Contains the arguments for the tool.
  - **job_id** (string) - Required - The unique identifier for the audiobook generation job.

### Request Example
```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "audiobook_status",
    "arguments": {
      "job_id": "<JOB_ID>"
    }
  }
}
```
```

--------------------------------

### Install spaCy for Fallback

Source: https://github.com/boltzmannentropy/mimikastudio/blob/main/README.md

Install the spaCy library if you see a 'spaCy not available' warning. The application will use a regex fallback if spaCy is not installed.

```bash
pip install spacy
```

--------------------------------

### Start MCP Server with mimikactl

Source: https://github.com/boltzmannentropy/mimikastudio/blob/main/README.md

Starts the MCP server on port 8010.

```bash
./bin/mimikactl mcp start
```

--------------------------------

### Start Flutter UI in Release Mode with mimikactl

Source: https://github.com/boltzmannentropy/mimikastudio/blob/main/README.md

Starts the Mimika Studio Flutter UI in release mode.

```bash
./bin/mimikactl flutter start
```

--------------------------------

### Verify MimikaStudio Installation

Source: https://github.com/boltzmannentropy/mimikastudio/blob/main/README.md

Run these Python commands in the activated virtual environment to verify that core libraries like Kokoro, Qwen3-TTS, Chatterbox, OmegaConf, and Perth are installed correctly.

```python
source venv/bin/activate
python -c "import kokoro; print('Kokoro OK')"
python -c "from qwen_tts import QwenTTS; print('Qwen3-TTS OK')"
python -c "from chatterbox import ChatterboxTTS; print('Chatterbox OK')"
python -c "import omegaconf; print('OmegaConf OK')"
python -c "import perth; print('Perth OK')"
```

--------------------------------

### Start Flutter UI in Development Mode with mimikactl

Source: https://github.com/boltzmannentropy/mimikastudio/blob/main/README.md

Starts the Mimika Studio Flutter UI in development mode.

```bash
./bin/mimikactl flutter start --dev
```

--------------------------------

### Install ffmpeg with Homebrew

Source: https://github.com/boltzmannentropy/mimikastudio/blob/main/README.md

Run this command to resolve 'ffmpeg not found' errors, which are relevant for MP3/M4B export functionality. It installs ffmpeg using Homebrew.

```bash
brew install ffmpeg
```

--------------------------------

### Install espeak-ng with Homebrew

Source: https://github.com/boltzmannentropy/mimikastudio/blob/main/README.md

Use this command if you encounter the 'espeak-ng not found' error. It installs the necessary dependency via Homebrew.

```bash
brew install espeak-ng
```

--------------------------------

### Download MimikaStudio Models

Source: https://github.com/boltzmannentropy/mimikastudio/blob/main/README.md

Pre-download AI models for MimikaStudio using the mimikactl command. The Dicta ONNX model can be downloaded separately if skipped during initial setup.

```bash
./bin/mimikactl models download kokoro   # ~300 MB
```

```bash
./bin/mimikactl models download qwen3    # ~4 GB for 1.7B
```

```bash
mkdir -p backend/models/dicta-onnx
curl -L -o backend/models/dicta-onnx/dicta-1.0.onnx \
  https://github.com/thewh1teagle/dicta-onnx/releases/download/model-files-v1.0/dicta-1.0.onnx
```

--------------------------------

### Install Chatterbox TTS Dependencies

Source: https://github.com/boltzmannentropy/mimikastudio/blob/main/README.md

Install the required Python packages for Chatterbox TTS if you encounter 'No module named 'perth'' or 'No module named 'omegaconf''. This includes activating the virtual environment and then installing the packages.

```bash
source venv/bin/activate
pip install resemble-perth omegaconf conformer diffusers pyloudnorm pykakasi spacy-pkuseg
pip install --no-deps chatterbox-tts==0.1.6
```

--------------------------------

### MCP Workflow: PDF to Audiobook

Source: https://github.com/boltzmannentropy/mimikastudio/blob/main/README.md

This workflow demonstrates generating an audiobook from a local PDF file using the MCP server. It includes starting the backend and MCP server, optionally confirming available voices, initiating the audiobook generation, and polling for status updates. The generated audio file will be saved locally and served via HTTP.

```bash
# 1) Start backend + MCP
./bin/mimikactl up --no-flutter
```

```bash
# 2) (Optional) confirm Kokoro voices via MCP
curl -s http://127.0.0.1:8010 \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"tts_list_voices","arguments":{"engine":"kokoro"}}}'
```

```bash
# 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"}}}'
```

```bash
# 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>"}}}'
```

--------------------------------

### MimiKastudio Project Directory Structure

Source: https://github.com/boltzmannentropy/mimikastudio/blob/main/README.md

This is a visual representation of the MimiKastudio project's directory layout. It details the purpose of each major directory and key files within them, including installation scripts, dependencies, service control scripts, the Flutter application, the FastAPI backend, and build scripts.

```bash
MimikaStudio/
├── install.sh                # Single install script (run this first)
├── requirements.txt          # All Python dependencies
├── venv/                     # Python virtual environment (created by install.sh)
│
├── bin/
│   ├── mimikactl             # Service control script
│   ├── mimika                # CLI tool for TTS/voice cloning
│   └── tts_mcp_server.py    # MCP server for programmatic access
│
├── pdf/                      # Place read-aloud documents here (pdf/txt/md/docx/epub)
│
├── flutter_app/              # Flutter desktop application (~10,100 lines Dart)
│   ├── lib/
│   │   ├── main.dart         # App entry, 6-tab navigation + Model Manager
│   │   ├── screens/
│   │   │   ├── quick_tts_screen.dart        # Kokoro TTS
│   │   │   ├── qwen3_clone_screen.dart      # Qwen3 voice cloning
│   │   │   ├── chatterbox_clone_screen.dart # Chatterbox voice cloning
│   │   │   ├── pdf_reader_screen.dart       # PDF reader with TTS
│   │   │   ├── mcp_endpoints_screen.dart    # MCP & API dashboard
│   │   │   └── models_dialog.dart           # Model download manager
│   │   ├── widgets/
│   │   │   ├── audio_player_widget.dart     # Shared audio player
│   │   │   └── multi_layer_text.dart        # Text overlay widget
│   │   └── services/ 
│   │       └── api_service.dart             # Backend API client (823 lines)
│   └── macos/                               # macOS configuration
│
├── backend/                  # FastAPI Python backend (~8,500 lines Python, 60+ endpoints)
│   ├── main.py              # API endpoints (2,078 lines)
│   ├── database.py          # SQLite initialization and seeding
│   ├── requirements.txt     # (legacy, use root requirements.txt)
│   ├── tts/                 # TTS engine wrappers
│   │   ├── kokoro_engine.py
│   │   ├── qwen3_engine.py        # Clone + CustomVoice
│   │   ├── chatterbox_engine.py   # Multilingual voice clone
│   │   ├── text_chunking.py       # Smart text chunking for audiobooks
│   │   ├── audio_utils.py         # Audio processing utilities
│   │   └── audiobook.py           # Audiobook generation logic (822 lines)
│   ├── language/
│   ├── llm/                 # LLM provider integration
│   │   ├── factory.py       # Claude, OpenAI, Ollama support
│   │   ├── claude_provider.py
│   │   ├── openai_provider.py
│   │   └── codex_provider.py
│   ├── models/ 
│   │   ├── registry.py      # Model registry (all engines)
│   │   └── dicta-onnx/      # Hebrew diacritizer (~1.1 GB, downloaded by install.sh)
│   ├── tests/               # Comprehensive test suite
│   └── data/
│       ├── samples/         # Shipped voice samples (shared across engines)
│       │   ├── qwen3_voices/      # Yelena, Svetlana
│       │   ├── chatterbox_voices/ # Yelena, Svetlana, Hebrew_Yelena
│       │   └── kokoro/            # Pre-generated Kokoro samples
│       ├── user_voices/     # User uploads (git-ignored, shared across engines)
│       │   ├── qwen3/
│       │   ├── chatterbox/
│       └── outputs/         # Generated audio files
│
├── scripts/                 # Build & installer scripts
│   ├── build_installer.ps1  # Windows installer build (PyInstaller + Inno Setup)
│   ├── mimikastudio.spec    # PyInstaller spec file
│   ├── mimikastudio.iss     # Inno Setup installer script
│   ├── install_macos.sh     # (legacy, use root install.sh)
│   └── setup.sh             # (legacy, use root install.sh)

```

--------------------------------

### Codex Prompt for Audiobook Generation

Source: https://github.com/boltzmannentropy/mimikastudio/blob/main/README.md

An example prompt for Codex to generate an audiobook from a PDF, poll its status, and return the job ID and audio URL. This assumes the client is connected to the Mimika MCP server.

```text
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.
```

--------------------------------

### Show Version Info with mimikactl

Source: https://github.com/boltzmannentropy/mimikastudio/blob/main/README.md

Displays the version information for Mimika Studio.

```bash
./bin/mimikactl version
```

--------------------------------

### Mimika Qwen3 TTS Basic Usage

Source: https://github.com/boltzmannentropy/mimikastudio/blob/main/README.md

Basic command structure for using the Qwen3 TTS engine. Supports text strings or file paths as input. Common parameters include --output, --model, --language, --temperature, --top-p, and --top-k for controlling generation.

```bash
./bin/mimika qwen3 <input> [options]
```

--------------------------------

### Clean and Build Flutter macOS App

Source: https://github.com/boltzmannentropy/mimikastudio/blob/main/README.md

Commands to clean the Flutter project, get dependencies, and build a release version for macOS. This is useful if the Flutter build fails.

```bash
flutter clean && flutter pub get && flutter build macos --release
```

--------------------------------

### Build macOS App with mimikactl

Source: https://github.com/boltzmannentropy/mimikastudio/blob/main/README.md

Builds the Mimika Studio macOS application.

```bash
./bin/mimikactl flutter build
```

--------------------------------

### Claude Code Prompt for Audiobook Generation

Source: https://github.com/boltzmannentropy/mimikastudio/blob/main/README.md

An example prompt for Claude Code to generate an audiobook from a PDF, track its status, and report the final audio URL. This assumes the client is connected to the Mimika MCP server.

```text
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.
```

--------------------------------

### Run API Tests with mimikactl

Source: https://github.com/boltzmannentropy/mimikastudio/blob/main/README.md

Executes API tests for Mimika Studio.

```bash
./bin/mimikactl test
```

--------------------------------

### Qwen3 Voice Clone from Reference Audio

Source: https://github.com/boltzmannentropy/mimikastudio/blob/main/README.md

Use the --clone and --reference flags to clone a voice from a provided audio file. The --reference-text flag can optionally be used to improve quality by providing a transcript of the reference audio.

```bash
./bin/mimika qwen3 "Hello, world!" --clone --reference Alina.wav
```

```bash
./bin/mimika qwen3 book.pdf --clone --reference Bella.wav --output book.wav
```

--------------------------------

### Run Backend Tests

Source: https://github.com/boltzmannentropy/mimikastudio/blob/main/README.md

Commands to activate the virtual environment, navigate to the backend directory, and run tests using pytest. Includes options for running all tests, specific files, or tests requiring model loading.

```bash
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/
```

--------------------------------

### Restart All Services with mimikactl

Source: https://github.com/boltzmannentropy/mimikastudio/blob/main/README.md

Restarts all Mimika Studio services.

```bash
./bin/mimikactl restart
```

--------------------------------

### Check Service Status with mimikactl

Source: https://github.com/boltzmannentropy/mimikastudio/blob/main/README.md

Displays the current status of Mimika Studio services.

```bash
./bin/mimikactl status
```

--------------------------------

### Tail Service Logs with mimikactl

Source: https://github.com/boltzmannentropy/mimikastudio/blob/main/README.md

Tails the logs for a specified service (backend, mcp, flutter, or all).

```bash
./bin/mimikactl logs [service]
```

--------------------------------

### List Available Voices for Qwen3 Engine

Source: https://github.com/boltzmannentropy/mimikastudio/blob/main/README.md

List all available voices for the Qwen3 TTS engine.

```bash
./bin/mimika voices --engine qwen3
```

--------------------------------

### List Available Voices for Kokoro Engine

Source: https://github.com/boltzmannentropy/mimikastudio/blob/main/README.md

List all available voices for the Kokoro TTS engine.

```bash
./bin/mimika voices --engine kokoro
```