Skip to content

README.md

Latest commit

 

History

History
380 lines (270 loc) · 12.2 KB

README.md

File metadata and controls

380 lines (270 loc) · 12.2 KB

Stream Daemon Documentation

📚 Complete guides for Stream Daemon - multi-platform stream announcement automation

Welcome to the Stream Daemon documentation! This directory contains comprehensive guides for setting up, configuring, and using Stream Daemon.

🚀 Getting Started

New to Stream Daemon? Start here:

🎮 Streaming Platform Setup

Configure Stream Daemon to monitor your live streams:

Supported Platforms

  • Twitch - OAuth 2.0 setup, client ID/secret, rate limits, troubleshooting
  • YouTube Live - API key, channel ID resolution, quota management
  • Kick - OAuth authentication, 2FA requirements, public API fallback

📱 Social Media Platform Setup

Configure where Stream Daemon posts your announcements:

Supported Platforms

  • Mastodon - Instance setup, access tokens, app creation, custom instances
  • Bluesky - App passwords, handle configuration, AT Protocol
  • Discord - Webhooks, rich embeds, role mentions, live updates, stream ended messages
  • Matrix - Bot creation, room setup, authentication methods (token/password)

⚙️ Configuration

Core Configuration

  • Secrets Wizard 🪄 NEW! - Interactive setup tool
    • Step-by-step credential configuration
    • Supports Doppler, AWS, Vault, and .env files
    • Loads existing values as defaults
    • Platform-specific guidance with credential links
  • Secrets Management ⭐ RECOMMENDED - Secure your credentials
    • Doppler setup (free, 10-minute setup, recommended)
    • AWS Secrets Manager (for AWS-heavy infrastructure)
    • HashiCorp Vault (for enterprise/self-hosted)
    • Priority system and best practices
    • Docker integration

✨ Features

Enhance your stream announcements with powerful features:

  • AI-Powered Messages 🤖 - Local or cloud AI generation

    • Ollama (local, private, free) or Google Gemini (cloud, easy setup)
    • Generate unique announcements for every stream
    • Platform-aware character limits
    • Automatic fallback to static messages
    • See Ollama Migration Guide to switch providers

  • LLM Model Recommendations 🎯 NEW! - Choose the right model for your GPU

    • VRAM-based recommendations (4GB to 24GB+)
    • Qwen 2.5, Gemma 3, LLaMA 3.1, Mistral comparisons
    • Optimized settings per model size
    • Multi-GPU setup guidance

  • Qwen3 Thinking Mode 🧠 EXPERIMENTAL - Support for Qwen3's reasoning models

    • Extract responses from Qwen3's "thinking" field
    • Automatic token limit adjustment
    • Pattern-based content extraction

  • Custom Messages - Personalize announcements

    • Platform-specific templates (Twitch, YouTube, Kick)
    • Variables: {url}, {title}, {game}, {viewers}
    • INI-style configuration
    • Migration from old format

  • Multi-Platform Streaming - Stream to multiple platforms simultaneously

    • Threading modes: separate, thread, combined
    • "Stream ended" strategies
    • Handle platform failures gracefully
    • Examples and scenarios

  • Multiple Streams Per Platform 🆕 NEW! - Monitor multiple streamers per platform

    • Track 3-5 streamers per platform
    • Comma-separated username lists
    • Independent state tracking for each stream
    • 100% backward compatible

🔄 Migration

Upgrading from an older version?

📖 Platform-Specific Guides

By Category

Streaming Platforms:

  • Twitch - Most popular streaming platform
  • YouTube Live - Google's streaming service
  • Kick - New competitor to Twitch

Social Media:

  • Mastodon - Federated microblogging
  • Bluesky - Decentralized social network
  • Discord - Chat and community platform
  • Matrix - Decentralized messaging

🎯 Common Tasks

First-Time Setup

  1. Install Stream Daemon - Choose Python, Docker, or cloud deployment
  2. Get API Credentials - Follow platform-specific guides
  3. Configure Secrets - Use Doppler for secure credential storage (recommended)
  4. Test Setup - Verify everything works
  5. Customize Messages - Make announcements your own

Advanced Configuration

🔍 Quick Reference

Configuration Files

File Purpose Required
.env Main configuration and credentials ✅ Yes
messages.txt Live stream announcement templates ⚠️ Optional
end_messages.txt Stream ended announcement templates ⚠️ Optional
docker-compose.yml Docker deployment configuration Only for Docker

Environment Variables

Essential:

# Enable platforms
TWITCH_ENABLE=True
MASTODON_ENABLE=True

# Platform credentials (or use secrets manager)
TWITCH_CLIENT_ID=xxx
MASTODON_ACCESS_TOKEN=yyy

# Check intervals
SETTINGS_CHECK_INTERVAL=5  # Minutes when offline
SETTINGS_POST_INTERVAL=5   # Minutes when live

Secrets Management (Recommended):

SECRETS_MANAGER=doppler
DOPPLER_TOKEN=dp.st.dev.xxx
SECRETS_DOPPLER_TWITCH_SECRET_NAME=TWITCH

See Secrets Management Guide for complete setup.

Command Reference

# Run Stream Daemon
python3 stream-daemon.py

# Run with Doppler
doppler run -- python3 stream-daemon.py

# Run in Docker
docker-compose up -d

# Test configuration
pytest tests/test_platform_validation.py -v

# Test specific platform
pytest tests/test_platform_validation.py::TestTwitchValidation -v

# View logs (systemd)
sudo journalctl -u stream-daemon -f

# View logs (Docker)
docker-compose logs -f stream-daemon

🆘 Troubleshooting

Common Issues

Stream not detected:

  1. Verify username is correct (case-sensitive)
  2. Check API credentials are valid
  3. Ensure platform is enabled (TWITCH_ENABLE=True)
  4. Lower check interval for faster detection

Announcements not posting:

  1. Test social platform authentication
  2. Verify webhooks/tokens are correct
  3. Check platform is enabled
  4. Review logs for errors

Doppler secrets not working:

  1. Verify token is correct (dp.st.dev.xxx)
  2. Check secret names match configured prefix
  3. Ensure environment matches token (dev token = dev secrets)
  4. Comment out credentials in .env (they override Doppler)

See: Quickstart Troubleshooting for detailed solutions.

🏗️ Architecture

Stream Daemon uses a modular architecture:

stream_daemon/
├── platforms/
│   ├── streaming/          # Monitor live streams
│   │   ├── twitch.py
│   │   ├── youtube.py
│   │   └── kick.py
│   └── social/             # Post announcements
│       ├── mastodon.py
│       ├── bluesky.py
│       ├── discord.py
│       └── matrix.py
├── secrets/                # Secrets management
│   ├── doppler.py
│   ├── aws.py
│   └── vault.py
└── utils/
    ├── ai_messages.py      # Gemini LLM integration
    └── message_parser.py   # Template variables

Flow:

  1. Daemon checks streaming platforms every CHECK_INTERVAL
  2. Detects state changes (offline→live or live→offline)
  3. Generates message (AI or template)
  4. Posts to all enabled social platforms
  5. Continues monitoring for stream end

📚 External Resources

Official Documentation

Secrets Management

AI Integration

🤝 Contributing

Want to improve Stream Daemon or its documentation?

How to Contribute

  1. Documentation improvements:

    • Fix typos or unclear sections
    • Add examples or troubleshooting tips
    • Translate guides to other languages

  2. Code contributions:

    • Add new platform integrations
    • Improve existing features
    • Fix bugs

  3. Community support:

    • Answer questions in Discussions
    • Share your Stream Daemon setup
    • Report bugs and suggest features

See Development Setup to get started.

📞 Support

Getting Help

Before Asking

Include this information for faster help:

  • Stream Daemon version - Check stream-daemon.py header
  • Python version - Run python3 --version
  • OS and platform - e.g., "Ubuntu 22.04", "macOS 13", "Docker"
  • Configuration - Enabled platforms (no credentials!)
  • Error messages - Full error output (secrets are auto-masked)
  • What you tried - Steps to reproduce the issue

Example:

**Version:** Stream Daemon v2.0.0
**Python:** 3.11.4
**OS:** Ubuntu 22.04 LTS
**Platforms:** Twitch + YouTube → Mastodon + Discord
**Secrets:** Doppler (dev environment)

**Error:**

ERROR: Failed to post to Mastodon: 401 Unauthorized


**Steps:**
1. Configured Mastodon with access token from instance settings
2. Token visible in Doppler dashboard
3. Test script succeeds, but daemon fails

⭐ Show Your Support

If Stream Daemon helps you grow your streaming presence:

  • ⭐ Star the repository - Help others discover it!
  • 📢 Share with streamers - Spread the word on social media
  • 💝 Donate - Support ongoing development
  • 🔧 Contribute - Submit pull requests and improvements

Made with ❤️ by ChiefGyk3D

Stream Daemon - Automate your multi-platform streaming presence

⬆ Back to Top • Main README