AudioNews - AI-Powered News Digests for Accessibility

Professional audio news service for visually impaired users • English, Polish & personalized content • Daily updates • Zero cost

🌐 audionews.uk • Updated daily at 6 AM UK time

🎙️ Podcast RSS Feeds:

• English (UK)
• Polish
• BellaNews

---

🎯 What It Does

Converts news headlines into natural-sounding audio digests using AI analysis and TTS (Edge TTS and ElevenLabs). Designed specifically for visually impaired users who need accessible news content.

Key Features

• 3 Active Services:
  • English (UK): General news digest
  • Polish: Polish news digest (excluding Radio Maria)
  • BellaNews: Personalized business/finance news for investment banking & VC interests
• AI-Enhanced: Claude 4.5 Sonnet analyzes and synthesizes content from multiple sources with context-aware generation to avoid repetition
• Premium Voices: Natural neural voices via Edge TTS and ElevenLabs (configurable per language)
• Accessible: WCAG 2.1 AA compliant, screen reader optimized, designed for blind and partially sighted users
• Podcast Distribution: RSS feeds available for Spotify, Apple Podcasts, and other platforms
• Automated: GitHub Actions generates and deploys daily
• Copyright Compliant: Synthesizes original summaries, never copies articles
• Cost Optimized: Only essential languages enabled to minimize API costs

📁 Project Structure

audio-transcription/
├── digest/               # Digest generation package
│   ├── config_loader.py  # Loads config JSONs, builds language configs
│   ├── models.py         # Data models (e.g. NewsStory)
│   ├── fetch.py          # Headline fetching from news sources
│   ├── ai_analysis.py    # AI story analysis and synthesis
│   ├── digest_synthesis.py # Digest text assembly and TTS normalization
│   └── tts.py            # TTS (Edge / Pocket / ElevenLabs) and audio output
├── scripts/              # Python scripts
│   ├── github_ai_news_digest.py      # Main generator (orchestrator)
│   ├── generate_podcast_rss.py       # Podcast RSS feed generator
│   ├── update_website.py             # Website updater
│   ├── update_language_website.py    # Language page updater
│   ├── create_all_language_pages.py  # Page generator
│   └── add_language.py               # Add new language
├── config/               # Configuration
│   ├── ai_prompts.json               # AI prompts & model settings
│   ├── voice_config.json             # Voice & TTS settings
│   └── README.md                     # Config documentation
├── docs/                 # GitHub Pages website
│   ├── en_GB/, pl_PL/, bella/       # Active language pages
│   │   ├── podcast.rss              # RSS feeds for podcast platforms
│   │   ├── audio/                   # MP3 audio files
│   │   └── index.html                # Language-specific pages
│   ├── images/                       # Podcast artwork (1400x1400px)
│   ├── shared/                       # Shared assets
│   └── index.html                    # Main entry
├── templates/            # HTML templates
├── tests/                # Unit and smoke tests
├── archive/              # Old/unused files
└── .github/workflows/    # CI/CD automation

🚀 Quick Start

Prerequisites

• Python 3.10+ (CI uses 3.11)
• ffmpeg (for audio silence compression; install via apt install ffmpeg / brew install ffmpeg)
• Git LFS (if you clone and need to pull existing audio: git lfs install then git lfs pull)

Local Development

# Install dependencies
pip install -r requirements.txt

# Setup git hooks (optional but recommended)
./scripts/setup-git-hooks.sh

# Full generation (uses Anthropic API; set ANTHROPIC_API_KEY)
python scripts/github_ai_news_digest.py --language en_GB
python scripts/github_ai_news_digest.py --language pl_PL
python scripts/github_ai_news_digest.py --language bella

# TTS-only test without API: use an existing transcript and Edge TTS
# python scripts/github_ai_news_digest.py --language en_GB --use-existing-transcript --tts-provider edge_tts

# Update website
python scripts/update_website.py

Note: Running full generation for all three languages uses Anthropic API credits (and ElevenLabs if you use --tts-provider elevenlabs). Use a single language or --use-existing-transcript to test without significant cost.

GitHub Actions Setup

1. Enable GitHub Pages (source: main branch, /docs folder)
2. Add secrets: ANTHROPIC_API_KEY (AI analysis) and ELEVENLABS_API_KEY (TTS for en_GB and bella in CI)
3. Workflow runs automatically daily at 5:00 UTC (6:00 AM UK)
4. Cost Optimization: Only English, Polish, and BellaNews are generated by default. Other languages are disabled in the workflow to minimize API costs. en_GB and BellaNews use ElevenLabs in CI; pl_PL uses Edge TTS.

See docs/GITHUB_ACTIONS_SETUP.md for detailed secrets setup, troubleshooting, and cost estimates.

🔧 Configuration

AI prompts and voice settings are externalized to JSON files for easy updates:

• config/ai_prompts.json: System messages, analysis/synthesis prompts, model settings
• config/voice_config.json: Voice configurations, TTS settings, retry logic

See config/README.md for detailed documentation.

🔍 Code Quality & Linting

Pre-commit Hook

The project includes a git pre-commit hook that automatically checks code quality before commits:

• ✅ Python syntax checking: Validates Python files for syntax errors
• ✅ JSON validation: Ensures JSON configuration files are valid
• ⚠️ Code quality warnings: Warns about trailing whitespace and tabs

Setup:

./scripts/setup-git-hooks.sh

The hook runs automatically on every commit. If errors are found, the commit is blocked until they're fixed.

What it checks:

• Python syntax errors (using py_compile)
• JSON file validity
• Trailing whitespace (warning only)
• Tab characters (warning only)

Bypassing (not recommended):

git commit --no-verify  # Skip pre-commit checks

Running tests

The tests/ directory contains unit and smoke tests:

• Config tests (no network): tests/test_config.py — checks that config/ JSON and digest config loader produce the expected structure.
• Pipeline smoke test (uses Edge TTS, needs network): tests/test_pipeline_smoke.py — runs the digest with a fixture transcript and verifies an MP3 is produced.

Run all tests from the project root:

python -m unittest discover -s tests -p "test_*.py" -v

Run only config tests (fast, no network):

python -m unittest tests.test_config -v

The smoke test uses AUDIONEWS_OUTPUT_BASE to write output to a temp dir so it does not modify docs/.

🍴 Forking & Customization

Want to create your own customized news service? Here's how:

1. Fork the Repository

Click the Fork button at the top of this page to create your own copy. If you clone and need to work with existing audio files, run git lfs install then git lfs pull.

2. Set Up Secrets

In your fork, go to Settings → Secrets and variables → Actions and add:

ANTHROPIC_API_KEY = your_anthropic_api_key_here
ELEVENLABS_API_KEY = your_elevenlabs_api_key_here

• Get your Anthropic key from Anthropic Console (used for AI analysis).
• Get your ElevenLabs key from ElevenLabs (used for en_GB and bella audio in CI; pl_PL uses Edge TTS and does not require it).

3. Customize AI Prompts

Edit config/ai_prompts.json to change:

• System messages (tone, style, instructions)
• Analysis prompts (how stories are categorized)
• Synthesis prompts (how summaries are generated)
• AI model settings (temperature, max tokens)

4. Customize Voices

Edit config/voice_config.json to:

• Change voices (browse Microsoft Edge TTS voices)
• Adjust retry logic
• Configure TTS settings

TTS providers: The digest supports edge_tts (default), pocket_tts (local, English), and elevenlabs. Use --tts-provider elevenlabs and set the ELEVENLABS_API_KEY environment variable (get keys at ElevenLabs). Voice IDs and options are in config/voice_config.json under tts_settings.elevenlabs.

5. Customize News Sources

News sources, themes, and per-language settings (greeting, output paths) are defined in the digest package. To add or change sources:

• AI prompts and model: Edit config/ai_prompts.json (system messages, analysis/synthesis prompts).
• Voices and TTS: Edit config/voice_config.json (voice names, provider, retry logic).
• Sources and themes: Edit digest/config_loader.py — update the templates structure for the language (e.g. sources, themes, greeting, output_dir).

The main script only orchestrates; it does not define sources or prompts.

6. Enable GitHub Pages

1. Go to Settings → Pages
2. Set Source to main branch, /docs folder
3. Set custom domain (optional)

7. Test Your Changes

# Test locally first
python scripts/github_ai_news_digest.py --language en_GB

# Check the generated files
ls docs/en_GB/audio/

8. Deploy

Push to main branch - GitHub Actions will automatically:

• Generate daily digests at 5:00 UTC
• Deploy to GitHub Pages
• Store audio files in Git LFS

🤝 Contributing

Pull requests are gratefully appreciated! Help improve this project:

Areas for Contribution

• 🌍 New languages - Add support for more regions
• 🎤 Voice improvements - Better voice selection or quality
• 🤖 AI enhancements - Improved prompts or analysis
• ♿ Accessibility - Better screen reader support
• 🎨 UI/UX - Design improvements
• 📚 Documentation - Clearer guides
• 🐛 Bug fixes - Report or fix issues

How to Contribute

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Test thoroughly
5. Commit with clear messages (git commit -m '✨ Add amazing feature')
6. Push to your fork (git push origin feature/amazing-feature)
7. Open a Pull Request

Contribution Guidelines

• Keep accessibility as the top priority
• Maintain copyright compliance
• Test changes locally before submitting
• Document new features in README or config files
• Follow existing code style
• Add comments for complex logic

All contributions, big or small, are valued and appreciated! 🙏

⚖️ Copyright & Ethics

This service synthesizes original content from multiple news sources:

✅ Creates transformative summaries through AI analysis
✅ Provides accessibility service for disabled users (fair use)
✅ Never copies substantial portions of articles
✅ Respects paywalls and access restrictions

See docs/COPYRIGHT_AND_ETHICS.md for complete legal framework.

📜 License

Source Code

The source code is licensed under the GNU General Public License v3.0 (GPL v3) - see LICENSE file for details.

This means:

• ✅ You can: Use, modify, and distribute the code
• ✅ You must: Keep the same license (GPL v3) for any derivatives
• ✅ You must: Make source code available when distributing

Generated Content

All generated audio content, transcripts, and news digests are licensed under Creative Commons Attribution-NonCommercial 4.0 (CC BY-NC 4.0).

• ✅ You can: Share, adapt, and use for non-commercial purposes
• ❌ You cannot: Use for commercial purposes or sell the content

See CONTENT_LICENSE.md for full details.

🌍 Adding New Languages

1. Add voice configuration to config/voice_config.json
2. Add AI prompts (system message, region name, synthesis template) to config/ai_prompts.json
3. Add the language template (sources, themes, greeting, output paths) in digest/config_loader.py (see existing entries in the templates structure)
4. Run python scripts/create_all_language_pages.py
5. To have CI generate the new language daily, add it to CORE_LANGUAGES or NEW_LANGUAGES in .github/workflows/daily-news-digest.yml

🎙️ Podcast Distribution

AudioNews generates RSS 2.0 feeds for each service that can be submitted to podcast platforms:

• English (UK): https://audionews.uk/en_GB/podcast.rss
• Polish: https://audionews.uk/pl_PL/podcast.rss
• BellaNews: https://audionews.uk/bella/podcast.rss

Features

• ✅ RSS 2.0 compliant with iTunes/Apple Podcasts extensions
• ✅ Automatic updates - New episodes added daily
• ✅ Full transcripts included in episode descriptions
• ✅ SEO optimized with keywords for blind and partially sighted users
• ✅ Artwork included - 1400x1400px podcast covers

Publishing to Platforms

1. Spotify: Submit RSS feed at Spotify for Podcasters
2. Apple Podcasts: Submit at Apple Podcasts Connect
3. Other platforms: Most platforms accept RSS feeds automatically

See docs/PODCAST_SETUP.md for detailed publishing instructions.

Automatic RSS Generation

RSS feeds are automatically regenerated daily when new content is published. Each feed includes:

• Last 50 episodes (RSS best practice)
• Episode metadata (titles, descriptions, dates)
• Audio file URLs
• Full transcripts in episode descriptions
• Podcast artwork and branding

📊 Tech Stack

• AI: Anthropic Claude 4.5 Sonnet
• TTS: Edge TTS and ElevenLabs (see config/voice_config.json; Edge uses +10% speed)
• CI/CD: GitHub Actions
• Hosting: GitHub Pages
• Storage: Git LFS for audio files
• PWA: Service Worker + manifest
• Podcasts: RSS 2.0 feeds with iTunes extensions

📞 Support

• Live Service: audionews.uk
• Podcast Setup Guide: docs/PODCAST_SETUP.md
• Issues: GitHub Issues
• Organization: Dynamic Devices

---

© 2025–2026 Dynamic Devices • Open Source • Made with ♿ accessibility in mind