https://github.com/dynamicdevices/audionews
AI-powered daily audio news digests for accessibility. Generates natural-sounding summaries using Claude AI and Edge TTS. Supports English, Polish, and personalized content. WCAG 2.1 AA compliant.
https://github.com/dynamicdevices/audionews
accessibility ai audio claude edge-tts english github-actions news news-digest polish pwa text-to-speech tts visually-impaired wcag
Last synced: 24 days ago
JSON representation
AI-powered daily audio news digests for accessibility. Generates natural-sounding summaries using Claude AI and Edge TTS. Supports English, Polish, and personalized content. WCAG 2.1 AA compliant.
- Host: GitHub
- URL: https://github.com/dynamicdevices/audionews
- Owner: DynamicDevices
- License: other
- Created: 2025-10-15T07:11:44.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2026-01-23T14:15:51.000Z (2 months ago)
- Last Synced: 2026-01-23T23:11:27.358Z (2 months ago)
- Topics: accessibility, ai, audio, claude, edge-tts, english, github-actions, news, news-digest, polish, pwa, text-to-speech, tts, visually-impaired, wcag
- Language: HTML
- Homepage: https://audionews.uk
- Size: 415 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# AudioNews - AI-Powered News Digests for Accessibility
[](https://github.com/DynamicDevices/audionews/actions/workflows/daily-news-digest.yml)
[](https://github.com/DynamicDevices/audionews/releases/latest)
[](https://audionews.uk)
[](https://audionews.uk)
**Professional audio news service for visually impaired users • English, Polish & personalized content • Daily updates • Zero cost**
🌐 **[audionews.uk](https://audionews.uk)** • Updated daily at 6 AM UK time
🎙️ **Podcast RSS Feeds**:
- [English (UK)](https://audionews.uk/en_GB/podcast.rss)
- [Polish](https://audionews.uk/pl_PL/podcast.rss)
- [BellaNews](https://audionews.uk/bella/podcast.rss)
---
## 🎯 What It Does
Converts news headlines into natural-sounding audio digests using AI analysis and Microsoft Edge TTS. 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 Microsoft Edge TTS
- **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/
├── scripts/ # Python scripts
│ ├── github_ai_news_digest.py # Main generator
│ ├── 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
├── archive/ # Old/unused files
└── .github/workflows/ # CI/CD automation
```
## 🚀 Quick Start
### Local Development
```bash
# Install dependencies
pip install -r requirements.txt
# Setup git hooks (optional but recommended)
./scripts/setup-git-hooks.sh
# Generate digest for English, Polish, or BellaNews
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
# Update website
python scripts/update_website.py
```
### GitHub Actions Setup
1. Enable GitHub Pages (source: `main` branch, `/docs` folder)
2. Add secret: `ANTHROPIC_API_KEY`
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.
## 🔧 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`](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:**
```bash
./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):**
```bash
git commit --no-verify # Skip pre-commit checks
```
## 🍴 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.
### 2. Set Up Secrets
In your fork, go to **Settings → Secrets and variables → Actions** and add:
```
ANTHROPIC_API_KEY = your_anthropic_api_key_here
```
Get your API key from [Anthropic Console](https://console.anthropic.com/).
### 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](https://speech.microsoft.com/portal/voicegallery))
- 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](https://elevenlabs.io/)). Voice IDs and options are in `config/voice_config.json` under `tts_settings.elevenlabs`.
### 5. Customize News Sources
Edit `scripts/github_ai_news_digest.py`:
- Modify `LANGUAGE_CONFIGS` to add/change news sources
- Change greetings, themes, or output directories
### 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
```bash
# 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`](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](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](CONTENT_LICENSE.md) for full details.
## 🌍 Adding New Languages
1. Add voice configuration to `config/voice_config.json`
2. Add AI prompts to `config/ai_prompts.json`
3. Add language config to `scripts/github_ai_news_digest.py`
4. Run `python scripts/create_all_language_pages.py`
## 🎙️ 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](https://podcasters.spotify.com/)
2. **Apple Podcasts**: Submit at [Apple Podcasts Connect](https://podcastsconnect.apple.com/)
3. **Other platforms**: Most platforms accept RSS feeds automatically
See [`docs/PODCAST_SETUP.md`](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**: Microsoft Edge TTS (neural voices, +10% speed adjustment)
- **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](https://audionews.uk)
- **Podcast Setup Guide**: [`docs/PODCAST_SETUP.md`](docs/PODCAST_SETUP.md)
- **Issues**: [GitHub Issues](https://github.com/DynamicDevices/audionews/issues)
- **Organization**: [Dynamic Devices](https://github.com/DynamicDevices)
---
**© 2025 Dynamic Devices • Open Source • Made with ♿ accessibility in mind**