mixcloud-rss-generator/README.md

Mixcloud RSS Generator (Backend CLI)

Convert Mixcloud shows into RSS feeds using a lightweight command-line interface that leverages shared content syndication services.

Features

• 🎵 Convert any Mixcloud user's shows into an RSS feed
• 📱 Compatible with podcast apps (Apple Podcasts, Overcast, etc.)
• 🚀 Fast with built-in caching
• 🔧 Backend-only CLI tool (no web interface)
• 📡 Advanced filtering options (keywords, dates, tags)
• ♻️ Uses shared services for reusability across projects

Architecture

This project has been refactored to use shared services:

• Backend Services: Located in shared/services/content_syndication/
• CLI Interface: src/cli.py provides command-line access
• Legacy Components: Web UI archived in archived_projects/mixcloud-ui/

Installation

# Navigate to the mixcloud-rss-generator directory
cd mixcloud-rss-generator

# Install dependencies
pip install -r requirements.txt

# Ensure shared services are accessible
export PYTHONPATH=/path/to/my-ai-projects:$PYTHONPATH

Usage

Basic Usage

Generate RSS feed from Mixcloud user:

# Basic RSS generation
python src/cli.py WRFG

# From full Mixcloud URL
python src/cli.py --url https://www.mixcloud.com/NTSRadio/

# Save to file with custom limit
python src/cli.py WRFG --limit 50 --output feed.xml

Advanced Filtering

# Filter by keywords in title
python src/cli.py WRFG --keywords "rap,public affairs" --limit 100

# Filter by date range
python src/cli.py WRFG --date-range 2024-01-01 2024-12-31

# Filter by specific dates
python src/cli.py WRFG --specific-dates "July 21,Aug 15,2024-09-01"

# Revolutionary African Perspectives only (convenience filter)
python src/cli.py WRFG --rap-only --limit 100

# Combine multiple filters
python src/cli.py WRFG --keywords "interview" --tags "house,techno" --limit 30

Utility Operations

# Validate user without generating feed
python src/cli.py WRFG --validate

# Get user information
python src/cli.py WRFG --user-info

# Verbose output for debugging
python src/cli.py WRFG --verbose

Integration with Podcast Apps

1. Generate RSS feed and save to a publicly accessible location
2. Use the file path or served URL in your podcast app:
   • Apple Podcasts: File → Add Show by URL
   • Overcast: Add URL → Plus button → Add URL
   • Pocket Casts: Search → Enter URL
   • Castro: Library → Sources → Plus → Add Podcast by URL

Shared Services Architecture

The RSS generation now uses modular services from shared/services/content_syndication/:

• ContentSyndicationService: Main orchestration service
• MixcloudAPIClient: Handles Mixcloud API interactions with caching
• RSSFeedGenerator: Creates RSS 2.0 compliant feeds
• FeedFilterService: Advanced content filtering capabilities

Configuration

Cache Settings

# Custom cache directory and TTL
python src/cli.py WRFG --cache-dir ./custom-cache --cache-ttl 7200

Environment Variables

• PYTHONPATH: Must include parent project directory for shared imports
• No other environment variables required for basic operation

Examples

Generate Filtered Feed

# In Python script
from shared.services.content_syndication import ContentSyndicationService

# Initialize service
service = ContentSyndicationService(cache_dir="./cache", cache_ttl=3600)

# Generate with filters
filters = {"keywords": "rap,public affairs", "start_date": "2024-01-01"}
rss_feed = service.generate_mixcloud_rss("WRFG", limit=50, filters=filters)

Integration with Main AI Project

# Use in podcast processing pipeline
from shared.services.content_syndication import ContentSyndicationService

service = ContentSyndicationService()
rss_feed = service.generate_rap_feed("WRFG", limit=100)  # Convenience method

# Save for podcast processing
with open("data/feeds/wrfg_rap.xml", "w") as f:
    f.write(rss_feed)

Migration Notes

From Web Interface

The web interface (web_app.py and templates/) has been archived to archived_projects/mixcloud-ui/. Key changes:

• Before: python src/web_app.py (Flask web server)
• After: python src/cli.py [options] (CLI tool)

From Legacy Script

The original mixcloud_rss.py remains for compatibility but new usage should prefer the CLI:

• Legacy: python src/mixcloud_rss.py username
• New: python src/cli.py username

Troubleshooting

Import Errors

# Ensure PYTHONPATH includes project root
export PYTHONPATH=/path/to/my-ai-projects:$PYTHONPATH
python src/cli.py WRFG --validate

Cache Issues

# Clear cache if experiencing stale data
rm -rf cache/*.json
python src/cli.py WRFG --verbose

API Errors

• User not found: Check username spelling and profile visibility
• No shows: User might have private shows or no content
• Rate limiting: Wait between requests or increase cache TTL

Advanced Usage

Specialized Feeds

The CLI includes convenience options for specialized content:

# Revolutionary African Perspectives shows only
python src/cli.py WRFG --rap-only --limit 200

# Recent interviews only  
python src/cli.py WRFG --keywords "interview" --date-range 2024-01-01 $(date +%Y-%m-%d)

Batch Processing

# Process multiple users
for user in WRFG NTSRadio ResidentAdvisor; do
    python src/cli.py $user --output "feeds/${user}.xml" --limit 50
done

Integration with AI Assistant

This RSS generator integrates with the Personal AI Assistant project for:

• Podcast Processing: RSS feeds enable episode detection
• Audio Analysis: Provides metadata for audio processing
• Content Monitoring: Automated feed checking for new episodes

License

MIT License - part of the Personal AI Assistant ecosystem.