Python Livestream Toolkit

Automate YouTube livestreams with scheduled text-to-speech overlays and background music. The project can stream either a static image or any URL while injecting news updates generated by your preferred language model.

Features

• Stream static images or websites directly to YouTube using FFmpeg
• Schedule news segments with TTS audio overlays
• Loop background music so the stream never goes silent
• Easily switch between several TTS models and language models

Supported TTS Models

• Google Gemini TTS (tts/gemini.py)
• Resemble AI Chatterbox (tts/chatterbox.py)
• Hugging Face Inference API (tts/huggingface.py)
• Sesame CSM 1B (tts/sesame_csm.py)
• ElevenLabs API (tts/elevenlabs.py)

Supported Language Models

• Google Gemini (llm/gemini.py)
• xAI Grok (llm/grok.py)

Quick Start

1. Clone and install dependencies

git clone https://github.com/yourusername/python_livestream.git
cd python_livestream
pip install -r requirements.txt
playwright install

2. Configure environment

Create a .env file (see .env.example) and set at least:

YOUTUBE_STREAM_KEY=<your-youtube-key>
GEMINI_API_KEY=<your-gemini-key>
HF_TOKEN=<huggingface-token>      # required for Hugging Face TTS
XAI_API_KEY=<grok-token>          # required for Grok LLM
ELEVENLABS_API_KEY=<11labs-key>   # required for ElevenLabs TTS
STREAM_URL=https://example.com    # optional website to stream
NEWS_INTERVAL_MINUTES=30          # minutes between news updates
STREAM_FPS=1                      # capture rate for website streaming

3. Run a livestream

To stream the static screenshot.png with background music:

python main.py

To livestream a website with scheduled news segments:

python stream_url.py

4. Generate a news video

Add a news voiceover to an existing video:

python create_video.py path/to/video.mp4 --output news_video.mp4

Run with Docker

Build the Docker image and start streaming:

docker build -t python-livestream .
docker run --env-file .env python-livestream

To stream a website instead of an image:

docker run --env-file .env python-livestream python stream_url.py

Additional Notes

• FFmpeg must be installed and available in your PATH.
• Replace screenshot.png and audio/song.mp3 with your own assets.
• The streaming scripts default to a video bitrate of 6800 Kbps, the rate YouTube recommends for 1080p streams.

Contributing

Please run the following before submitting a pull request:

python -m py_compile $(git ls-files '*.py')

License

MIT