voicci

v1.1.2

Published

14 days ago

AI-Powered Audiobook Generator for Claude Code, OpenCode & AI Code Editors. Convert books and PDFs to audiobooks using natural language.

🎧 Voicci - AI-Powered Audiobook Generator

Transform books and PDFs into audiobooks using natural language with Claude Code, OpenCode, or any AI code editor.

Designed for AI Assistants - Just tell your AI what book you want, and it handles the search, download, conversion, and summarization automatically.

Features

📚 Smart Book Search - Find and download books by name (no file paths needed)
📝 AI Summarization - Generate analytical summaries at 2-5% of original length
🎯 Natural Voice - XTTS v2 generates human-like speech with emotion
📖 PDF & Text Support - Intelligent text extraction with auto-cleaning
🧹 Smart Cleaning - Removes page numbers, headers, footers, TOC
📑 Chapter Detection - Automatically identifies and processes chapters
⚡ Background Processing - Jobs run independently with persistent queue
📊 Progress Tracking - Real-time CLI UI shows chapter-by-chapter progress
⚙️ Smart Configuration - Auto-detects system capabilities and optimizes settings
💾 Memory Management - Optional monitoring to prevent system instability
🎛️ Quality Presets - Fast, balanced, or best quality generation
🔄 Concurrent Processing - Process multiple books simultaneously (based on your system)
🍎 Apple Silicon - Optimized for Metal acceleration (M1/M2/M3)
🔒 100% Local - No cloud, no tracking, no data collection

Quick Start

Installation

Prerequisites (one-time):

Node.js 22+
Python 3.10+
pip3 install TTS torch torchaudio — Voicci uses XTTS v2 locally (PyTorch + Coqui TTS; ~2 GB of model weights download on first run)

Install the CLI:

npm install -g voicci

Verify everything is wired up:

voicci doctor

voicci doctor prints a PASS/FAIL table for Node, Python, TTS, PyTorch, acceleration (MPS/CUDA/CPU), and the AI-editor skill directory. If anything fails, it tells you the exact command to fix it.

The npm package installs the CLI plus the Claude Code / OpenCode / Cursor / Windsurf skill files. Restart your AI editor after install so it picks up /voicci.

Usage with AI Code Editors

Claude Code (Recommended)

/voicci Lord of the Rings
/voicci search "neural networks book"
/voicci summary mybook.pdf

Claude AI will:

Search for books intelligently
Handle ambiguity and pick the best match
Monitor conversion progress
Troubleshoot errors automatically
Guide you through summarization

OpenCode

Find and convert "Attention Is All You Need" paper to audiobook

OpenCode will understand your intent and run the appropriate voicci commands.

Cursor / Windsurf / Other AI Editors

Simply tell your AI assistant what you want in natural language:

"Convert this PDF to an audiobook"
"Find me a book about machine learning and turn it into audio"
"Summarize this paper for me"

The AI will intelligently use the voicci CLI commands to accomplish the task.

CLI Reference (For Advanced Users)

These commands are typically run by your AI assistant, but you can also use them directly:

Convert by Book Name (Recommended)

# Just name the book - Voicci finds and downloads it
voicci "The Great Gatsby"
voicci "Attention Is All You Need"  # Academic papers too!
voicci "1984 by George Orwell"

Convert from File

# PDF or TXT file
voicci mybook.pdf
voicci story.txt

Search Without Downloading

# Preview search results before downloading
voicci --search "The Catcher in the Rye"

Generate Summaries

# Generate analytical summary only (no audio)
voicci summary mybook.pdf
voicci --summary "The Great Gatsby"

# Generate both audiobook AND summary
voicci --with-summary mybook.pdf
voicci --with-summary "1984"

Summary Features:

Analytical style with clear, non-specialized vocabulary
Retains specificity (key details, names, numbers, facts)
Adaptive length: 2-5% of original word count depending on document size
Three backends: Ollama (local LLM), Python AI, or extractive fallback
Saves summary as text file with statistics

Monitor Progress

# Live progress UI with chapter status
voicci -s <jobId>

# List all jobs
voicci -s

Manage Audiobooks

# List completed audiobooks
voicci -l

# Open audiobook folder
voicci -o <jobId>

# Delete audiobook
voicci -d <jobId>

# Cancel running job
voicci --cancel <jobId>

Configuration

# View current configuration
voicci config show

# Set memory profile (low, medium, high)
voicci config set-profile high

# Set quality preset (fast, balanced, best)
voicci config set-quality balanced

# Toggle memory monitoring
voicci config set-monitoring on

# View system recommendations
voicci config recommend

# Check memory status
voicci memory

How It Works

Audiobook Generation

Search & Download - Finds book from LibGen, Anna's Archive, or other sources
Text Extraction - Extracts clean text from PDF or reads text file
Smart Cleaning - Removes noise (page numbers, headers, footers, TOC)
Chapter Detection - Identifies chapter boundaries automatically
Sentence Splitting - Breaks text into sentences for natural prosody
Audio Generation - XTTS v2 generates high-quality speech
Background Processing - Runs independently with persistent queue
Progress Tracking - Real-time CLI UI shows status

Summary Generation

Text Extraction - Same extraction and cleaning as audiobook generation
Length Calculation - Determines target word count (2-5% based on document size)
AI Processing - Uses Ollama (local LLM), Python AI, or extractive summarization
Quality Assurance - Ensures analytical style with clear language
Output - Saves summary as text file with statistics and metadata

Book Sources

Voicci searches multiple sources automatically:

Library Genesis - Largest collection of academic books
Anna's Archive - Comprehensive shadow library
Z-Library - Alternative source (requires auth)

All sources are accessed via scripted HTTP requests (no APIs, no credentials).

File Locations

macOS

Audiobooks: ~/Library/Application Support/voicci/audiobooks/
Config: ~/Library/Application Support/voicci/config/
Cache: ~/Library/Caches/voicci/
Logs: ~/Library/Application Support/voicci/logs/

Linux

Audiobooks: ~/.local/share/voicci/audiobooks/
Config: ~/.config/voicci/
Cache: ~/.cache/voicci/
Logs: ~/.local/share/voicci/logs/

System Requirements

Voicci automatically detects your system capabilities and configures itself optimally.

Minimum (Low Profile)

RAM: 2GB
Storage: 1GB free space
CPU: 2 cores
Max file size: 50MB, 1 job at a time

Recommended (Medium Profile)

RAM: 4-8GB (auto-detected)
Storage: 5GB free space
CPU: 4 cores
Max file size: 100MB, 2 jobs simultaneously

Optimal (High Profile)

RAM: 8GB+ (auto-detected)
Storage: 10GB+ free space
CPU: 8+ cores
Max file size: 500MB, 5 jobs simultaneously

Dependencies

Node.js 18+
Python 3.9+
pdftotext (from Poppler) - optional for PDF support

Performance

XTTS v2 prioritizes quality over speed:

Average: ~150-200 words/minute
Novel (80k words): 2-4 hours on Apple Silicon
Paper (10k words): 30-60 minutes

Jobs run in the background so you can continue working.

Configuration System

Voicci features a smart configuration system that automatically optimizes settings based on your hardware.

Memory Profiles

| Profile | RAM | Max File | Jobs | Monitoring | Best For | |---------|-----|----------|------|------------|----------| | low | 2-4GB | 50MB | 1 | Enabled | Budget laptops, older machines | | medium | 4-8GB | 100MB | 2 | Enabled | Typical consumer laptops | | high | 8GB+ | 500MB | 5 | Disabled | Modern machines, workstations |

# View available profiles
voicci config profiles

# Switch profile
voicci config set-profile medium

Quality Presets

| Preset | Speed | Quality | Best For | |--------|-------|---------|----------| | fast | Fastest | Good | Testing, drafts | | balanced | Medium | Very Good | Recommended (default) | | best | Slower | Excellent | Final audiobooks |

# View available presets
voicci config presets

# Switch preset
voicci config set-quality best

Memory Monitoring

Optional monitoring that warns when memory usage is high:

Auto-enabled: On low/medium profiles (systems with <8GB RAM)
Auto-disabled: On high profile (systems with 8GB+ RAM)

# Enable monitoring
voicci config set-monitoring on

# Disable monitoring
voicci config set-monitoring off

# Check current status
voicci memory

Configuration File

Settings are stored in ~/.config/voicci/settings.json (XDG Base Directory compliant):

{
  "version": "1.0.0",
  "memoryProfile": "high",
  "qualityPreset": "balanced",
  "autoDetectProfile": true,
  "enableMemoryMonitoring": null,
  "profileManuallySet": false,
  "customSettings": {}
}

Troubleshooting

Python version error

Ensure Python 3.9+ is installed:

python3 --version

Model download fails

Check internet connection during installation. Model (~450MB) is downloaded once.

PDF not extracting

Install poppler-utils for pdftotext:

# macOS
brew install poppler

# Linux
sudo apt-get install poppler-utils

Metal not available

Requires macOS 12+ on Apple Silicon. Falls back to CPU if unavailable.

Book search failing

Sources may be temporarily unavailable. Try:

Different book title or author name
Using file path directly: voicci mybook.pdf
Checking internet connection

Development

# Run tests
npm test

# Start worker manually
npm run worker

# Test text cleaner
node tests/test-cleaner.js

# Check queue status
sqlite3 ~/Library/Application\ Support/voicci/queue.db "SELECT * FROM jobs;"

Architecture

voicci/
├── cli/              # Command-line interface
│   ├── index.js      # Main CLI commands
│   └── progress-ui.js # React Ink progress UI
├── lib/              # Core libraries
│   ├── config.js     # Configuration & paths
│   ├── config-manager.js # Smart configuration system
│   ├── text-cleaner.js # PDF/text extraction & cleaning
│   ├── summarizer.js # AI text summarization
│   ├── tts-engine.py  # XTTS v2 wrapper
│   ├── queue.js      # SQLite job queue
│   ├── book-finder.js # Multi-source book search
│   ├── path-validator.js # Security: path validation
│   └── memory-monitor.js # Optional memory monitoring
├── backend/          # Background processing
│   └── worker.js     # Job processor with retry logic
└── tests/            # Test files
    ├── test-security.js # Security validation
    └── test-cleaner.js  # Text cleaning tests

Privacy & Security

100% Local Processing - No cloud services, no API keys
No Data Collection - Your files never leave your machine
No Tracking - No analytics, no telemetry
Open Source - Fully auditable code

License

MIT License - Free to use, modify, and distribute.

Credits

XTTS v2 by Coqui AI
PyTorch for deep learning framework
Book Sources: LibGen, Anna's Archive, Z-Library

Support

For issues, questions, or feature requests:

Website: https://voicci.com/voicci-cli
Email: [email protected]

Made with ❤️ by Voicci