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

```bash
# 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:

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```python
# 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

```python
# 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
```bash
# Ensure PYTHONPATH includes project root
export PYTHONPATH=/path/to/my-ai-projects:$PYTHONPATH
python src/cli.py WRFG --validate
```

### Cache Issues
```bash
# 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:

```bash
# 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

```bash
# 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.