{"id":51412058,"url":"https://github.com/themotionmachine/vox-biblios","last_synced_at":"2026-07-04T15:32:20.218Z","repository":{"id":364662702,"uuid":"863090412","full_name":"themotionmachine/vox-biblios","owner":"themotionmachine","description":"A personal text-to-podcast generator that converts text files and web content into podcast episodes.","archived":false,"fork":false,"pushed_at":"2026-06-13T23:41:19.000Z","size":55230,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-14T01:07:50.103Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/themotionmachine.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-09-25T17:39:33.000Z","updated_at":"2026-06-13T23:41:22.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/themotionmachine/vox-biblios","commit_stats":null,"previous_names":["themotionmachine/vox-biblios"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/themotionmachine/vox-biblios","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/themotionmachine%2Fvox-biblios","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/themotionmachine%2Fvox-biblios/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/themotionmachine%2Fvox-biblios/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/themotionmachine%2Fvox-biblios/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/themotionmachine","download_url":"https://codeload.github.com/themotionmachine/vox-biblios/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/themotionmachine%2Fvox-biblios/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35127443,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-04T02:00:05.987Z","response_time":113,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-07-04T15:32:18.147Z","updated_at":"2026-07-04T15:32:20.213Z","avatar_url":"https://github.com/themotionmachine.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Vox Biblios\n\nA personal text-to-podcast generator that converts text files and web content into podcast episodes.\n\n## Features\n\n- **Text-to-Podcast Conversion**: Process text files or web content into audio podcast episodes\n- **Multiple TTS Providers**:\n  - **Pocket TTS** (default): High-quality local neural TTS with multiple voices (alba, marius, javert, jean, fantine, cosette, eponine, azelma)\n  - **Kokoro**: Local neural TTS via MLX (Apple Silicon), 18 voices, very fast long-form generation (optional extra)\n  - **AWS Polly**: Cloud-based neural TTS with many voice options\n  - **macOS Say**: Quick local generation using built-in macOS speech synthesis\n- **Local Mode**: `--output-dir` writes MP3s to a local folder — no AWS account needed\n- **One MP3 per Article**: Long texts are chunked, synthesized, and concatenated into a single episode\n- **RSS Feed Generation**: Automatically generate and update an RSS feed for podcast distribution\n- **Agent/Script Friendly**: `--json` output on stdout (logs go to stderr), `--dry-run` text preview, meaningful exit codes (0 success, 1 failure, 2 partial), stdin input\n- **Text Previews**: Includes text previews in episode descriptions for better context\n- **Cost Monitoring**: Built-in AWS cost estimation and monitoring\n- **Web Scraping**: Extract content from URLs for processing\n- **Automatic Text Cleanup**: Removes URLs, citations, number tables, captions, page numbers, separators, and bibliography sections before conversion\n- **Flexible Input**: Accept a folder, a single text file, a web URL, or stdin (`-`)\n- **Command Line Interface**: Easy-to-use CLI for all operations\n\n## Installation\n\n### Prerequisites\n\n- Python 3.10 or higher\n- **ffmpeg**: Required for audio conversion and concatenation (`brew install ffmpeg` on macOS)\n- AWS account with S3 access — **only** if you want to publish to an RSS feed or use the Polly provider. Local mode (`--output-dir`) needs no AWS setup.\n\n### Platform-Specific Features\n\n**All platforms:**\n- Pocket TTS (default): Local neural TTS\n- AWS Polly: Cloud TTS (requires AWS account and credentials)\n\n**Apple Silicon only:**\n- `--provider kokoro` uses Kokoro-82M via MLX. Install the extra: `uv tool install '.[kokoro]'` or `pip install 'vox-biblios[kokoro]'`\n\n**macOS only:**\n- `--provider say` uses the macOS built-in `say` command\n\n### Global Installation (Recommended)\n\nInstall vox-biblios as a global command that works from any directory without virtual environment activation.\n\n#### Option 1: Using uv (Recommended)\n\n```bash\n# Install uv if not already installed\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Clone the repository\ngit clone https://github.com/themotionmachine/vox-biblios.git\ncd vox-biblios\n\n# Install vox-biblios globally from local directory\nuv tool install .\n```\n\nOr install directly from GitHub without cloning:\n\n```bash\nuv tool install git+https://github.com/themotionmachine/vox-biblios.git\n```\n\n#### Option 2: Using pipx\n\n```bash\n# Install pipx if not already installed\npython3 -m pip install --user pipx\npipx ensurepath\n\n# Clone the repository\ngit clone https://github.com/themotionmachine/vox-biblios.git\ncd vox-biblios\n\n# Install vox-biblios globally from local directory\npipx install .\n```\n\nOr install directly from GitHub:\n\n```bash\npipx install git+https://github.com/themotionmachine/vox-biblios.git\n```\n\nAfter installation, the `vox-biblios` command will be available globally:\n\n```bash\nvox-biblios config init    # Set up configuration\nvox-biblios process text-q/  # Use from anywhere\n```\n\n\u003e **Note**: Once published to PyPI, you'll be able to install with just `uv tool install vox-biblios` or `pipx install vox-biblios`.\n\n### Development Installation\n\nFor local development or if you prefer the project-based approach:\n\n#### Quick Setup with Scripts\n\n```bash\n# Install and set up Vox Biblios\n./setup_voxbiblios.sh\n\n# Run Vox Biblios (automatically activates venv)\n./run_voxbiblios.sh [command]\n```\n\n#### Manual Setup with uv\n\n```bash\n# Create and activate a virtual environment\nuv venv\nsource .venv/bin/activate\n\n# Install in development mode\nuv sync\n\n# Use the command (within activated venv)\nvox-biblios [command]\n```\n\n## Configuration\n\nVox Biblios reads configuration from environment variables and config files. Configuration files are searched in the following priority order:\n\n1. `./.env.local` (current directory - for development)\n2. `~/.config/vox-biblios/config.env` (XDG config directory - recommended for global install)\n3. `~/.vox-biblios.env` (home directory - alternative location)\n4. Environment variables already set in your shell\n\n### Quick Configuration Setup\n\nFor global installation, use the interactive config initialization:\n\n```bash\nvox-biblios config init\n```\n\nThis will guide you through setting up your configuration file at `~/.config/vox-biblios/config.env`. AWS credentials may be left blank for local-only usage.\n\nFor scripted setups, use the non-interactive mode:\n\n```bash\nvox-biblios config init --non-interactive \\\n  --podcast-name \"My Podcast\"\n# Add --aws-access-key/--aws-secret-key/--s3-bucket only if publishing to S3\n# Use --force to overwrite an existing config file\n```\n\n### Manual Configuration\n\nCreate a configuration file in one of the locations above:\n\n```bash\n# For global installation (recommended)\nmkdir -p ~/.config/vox-biblios\nnano ~/.config/vox-biblios/config.env\n\n# OR for development (project directory)\nnano .env.local\n```\n\nAdd your configuration settings:\n\n```bash\n# Required only for S3/RSS publishing or the Polly provider\nAWS_ACCESS_KEY=your_access_key_here\nAWS_SECRET_KEY=your_secret_key_here\n\n# Optional (with defaults shown)\nAWS_REGION=us-east-1\nS3_BUCKET=vox-biblios\nPOLLY_VOICE_ID=Joanna\nPODCAST_NAME=Vox Biblios\nPODCAST_WEBSITE=vox-biblios.example.com\n```\n\n### Configuration Management Commands\n\n```bash\nvox-biblios config show  # Show where configuration is loaded from\nvox-biblios config init  # Interactive configuration setup\nvox-biblios config edit  # Edit configuration in your default editor\n```\n\n### Available Configuration Variables\n\nPublish target (see [Publish targets](#publish-targets)):\n\n- `VB_TARGET`: Default destination for `process` — `cloudflare` (default), `s3`, or `local`\n- `CONTROL_PLANE_URL`: Control-plane base URL (default: `https://vb.activationlayer.org`)\n- `CONTROL_PLANE_TOKEN`: Control-plane queue bearer token (required for the `cloudflare` target)\n\nAWS variables (required only for the `s3` target or the Polly provider):\n\n- `AWS_ACCESS_KEY`: Your AWS access key\n- `AWS_SECRET_KEY`: Your AWS secret key\n\nTTS configuration:\n\n- `TTS_PROVIDER`: Default TTS provider (default: pocket-tts). Options: pocket-tts, kokoro, polly, say\n- `TTS_VOICE`: Default voice for TTS (provider-specific)\n- `POCKET_TTS_VOICE`: Default voice for Pocket TTS (default: alba). Options: alba, marius, javert, jean, fantine, cosette, eponine, azelma\n- `POCKET_TTS_MODEL`: Pocket TTS model checkpoint (default: english_2026-04)\n\nOptional environment variables:\n\n- `PREVIEW_LENGTH`: Number of text characters to include in episode descriptions (default: 100)\n- `CHUNK_SIZE`: Maximum character size for text chunks (default: 90000)\n- `AWS_REGION`: AWS region to use (default: us-east-1)\n- `S3_BUCKET`: S3 bucket for storing audio files (default: vox-biblios)\n- `POLLY_VOICE_ID`: AWS Polly voice to use (default: Joanna)\n- `POLLY_ENGINE`: Polly engine to use (default: neural)\n- `POLLY_FORMAT`: Output audio format (default: mp3)\n- `POLLY_KEY_PREFIX`: S3 key prefix for audio files (default: audio)\n- `RSS_FILENAME`: Name of the RSS feed file (default: voxbiblios.rss)\n- `PODCAST_NAME`: Podcast title (default: Vox Biblios)\n- `PODCAST_DESCRIPTION`: Podcast description\n- `PODCAST_WEBSITE`: Website URL for the podcast\n- `PODCAST_IMAGE`: URL to podcast artwork\n- `LOG_LEVEL`: Logging level (default: INFO)\n\nAll other settings have sensible defaults, but you can customize them as needed.\n\n## Usage\n\n### Default Behavior\n\nWhen run without arguments, Vox Biblios processes all `.txt` files in the `text-q` directory (created automatically if it doesn't exist):\n\n```bash\nvox-biblios  # Processes text-q/ directory\n```\n\n### Basic Commands\n\nProcess text files in a directory (uses Pocket TTS by default):\n\n```bash\nvox-biblios process path/to/text/files/\n```\n\nProcess a single text file, a URL, or stdin:\n\n```bash\nvox-biblios process notes.txt\nvox-biblios process https://example.com/article\ncat article.txt | vox-biblios process -\n```\n\n### Publish targets\n\n`process` chooses where to publish via `--target` (default: `cloudflare`,\noverridable with `VB_TARGET` in your config):\n\n| Target | What it does |\n|---|---|\n| `cloudflare` *(default)* | Submits the URL/text to the [control-plane](worker/README.md) queue at `CONTROL_PLANE_URL`; the host poller synthesizes and publishes to `vb.activationlayer.org`. Needs `CONTROL_PLANE_TOKEN`. No synthesis or AWS on this path. |\n| `s3` | Legacy direct mode: synthesizes locally, uploads the MP3, and regenerates the RSS feed in S3/R2. Needs AWS (or R2) credentials. |\n| `local` | Writes MP3s to `--output-dir` and skips publishing entirely. No network/AWS. |\n\n```bash\nvox-biblios process https://example.com/article          # -\u003e control-plane queue (default)\nvox-biblios process notes.txt --feed essays              # -\u003e a specific control-plane feed\nvox-biblios process notes.txt --target s3                # -\u003e legacy S3 direct upload + RSS\nvox-biblios process notes.txt --target local --output-dir ~/Podcasts\n```\n\nIf `cloudflare` is the default but `CONTROL_PLANE_TOKEN` isn't set, `process`\n**errors with guidance** rather than silently falling back to the legacy S3 feed.\n\n### Local Mode (no AWS)\n\nWrite MP3s to a local folder instead of publishing (`--output-dir` implies\n`--target local`):\n\n```bash\nvox-biblios process notes.txt --output-dir ~/Podcasts\n```\n\n### Agent / Scripting Mode\n\nMachine-readable output on stdout (all logs go to stderr):\n\n```bash\nvox-biblios process notes.txt --output-dir ./out --json\n```\n\nPreview the cleaned text without synthesizing any audio:\n\n```bash\nvox-biblios process notes.txt --dry-run          # plain text\nvox-biblios process notes.txt --dry-run --json   # JSON per file\n```\n\nExit codes: `0` all episodes succeeded, `1` everything failed, `2` partial success. Source `.txt` files are only deleted from the queue folder after their episode succeeds.\n\n### TTS Provider Selection\n\nUse a specific TTS provider:\n\n```bash\n# Use Pocket TTS (default) - local neural TTS\nvox-biblios process path/to/text/files/\n\n# Use Kokoro - local neural TTS via MLX (Apple Silicon, requires the kokoro extra)\nvox-biblios process --provider kokoro path/to/text/files/\n\n# Use AWS Polly - cloud neural TTS\nvox-biblios process --provider polly path/to/text/files/\n\n# Use macOS say - local system TTS (macOS only)\nvox-biblios process --provider say path/to/text/files/\n```\n\nSelect a specific voice:\n\n```bash\n# Use a different Pocket TTS voice\nvox-biblios process --voice marius path/to/text/files/\n\n# Use a specific Polly voice\nvox-biblios process --provider polly --voice Matthew path/to/text/files/\n```\n\nList available voices for all providers:\n\n```bash\nvox-biblios voices\n\n# Or for a specific provider\nvox-biblios voices --provider pocket-tts\n```\n\n### Other Commands\n\nClear the podcast feed:\n\n```bash\nvox-biblios clear\n```\n\nCheck AWS cost estimates:\n\n```bash\nvox-biblios cost\n```\n\nShow version information:\n\n```bash\nvox-biblios version\n```\n\n### Command Options\n\n**Process Command Options:**\n- `--provider {pocket-tts,kokoro,polly,say}`: TTS provider to use (default: pocket-tts)\n- `--voice VOICE`: Voice to use for TTS (provider-specific)\n- `--output-dir DIR`: Write MP3s locally instead of uploading to S3/RSS\n- `--dry-run`: Show the cleaned text that would be synthesized, then exit\n- `--json`: Emit machine-readable JSON results on stdout\n- `-v, --verbose`: Enable verbose output for debugging\n\n### Text File Format\n\nVox Biblios accepts any plain text files with `.txt` extension. No special formatting is required.\n\n### RSS Feed\n\nThe generated RSS feed is uploaded to your S3 bucket and is available at:\n\n```\nhttps://s3.{region}.amazonaws.com/{bucket}/{rss_filename}\n```\n\nThis URL can be added to podcast players to subscribe to your generated podcast.\n\n### Scripting and Automation\n\nVox Biblios can be integrated into automation pipelines. When installed globally, you can use the `vox-biblios` command directly in shell scripts without any virtual environment setup.\n\n```bash\n#!/bin/bash\n# nightly.sh - run from cron or other schedulers\nset -e\n\n# Process a folder of new articles\nvox-biblios process /data/new-articles\n```\n\nFor development installations, use the provided wrapper script:\n\n```bash\n#!/bin/bash\n# nightly.sh - for development setup\nset -e\n\ncd /path/to/vox-biblios\n./run_voxbiblios.sh process /data/new-articles\n```\n\nSchedule this script with `cron` or another job runner to automatically convert new text files and upload the updated RSS feed.\n\n\n\n## Architecture\n\nVox Biblios follows a modular architecture:\n\n- **Core**: Central podcast manager and text processing\n- **TTS**: Unified TTS provider interface with implementations for Pocket TTS, AWS Polly, and macOS Say\n- **AWS**: Integration with AWS services (Polly, S3, Cost Explorer)\n- **Adapters**: External service integrations (RSS, web scraper)\n- **Utils**: Shared utilities (logging, helpers)\n- **CLI**: Command line interface\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthemotionmachine%2Fvox-biblios","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthemotionmachine%2Fvox-biblios","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthemotionmachine%2Fvox-biblios/lists"}