EchoTube is a lightweight, self-hosted bot that monitors YouTube channels or playlists for new videos containing specific keywords and posts ultra-clean notifications to Discord via webhooks.
Built with modern Node.js 20+ features, zero external dependencies (except RSS parser), and production-ready security.
- 🎯 Smart YouTube Monitoring - RSS-based channel and playlist tracking
- 🔍 Flexible Keyword Matching - Case-insensitive "any" or "all" matching modes
- 🎨 Ultra-Clean Discord Embeds - Minimal design with large thumbnails (1280x720)
- 🌐 Multi-Server Support - Post to multiple Discord servers simultaneously
- 🛠️ Zero Configuration Complexity - Pure environment variable setup
- 📦 Single Docker Container - Production-ready with security hardening
- 🧠 Intelligent Caching - Prevents duplicates with timestamp-based recovery
- 🧪 Comprehensive Test Mode - Safe validation without posting to Discord
- 📊 Production Logging - Structured JSON logs with configurable levels
- 🚀 Smart Initial Run - Won't spam Discord on first startup
# This is completely safe - it won't post anything to Discord
docker run --rm \
-e ET_TEST_MODE=true \
-e ET_CHANNEL_IDS=UCexample1 \
-e ET_KEYWORDS=minecraft,gaming \
-e ET_LOG_LEVEL=DEBUG \
richardthornton/echotube:latestYou'll need:
- 🔗 Discord Webhook URL(s) - Create one here (can use multiple for different servers)
- 📺 YouTube Channel IDs - Found in URLs (format:
UCxxxxxxxxxxxxxxxxxx) - 🔍 Keywords - What words to look for in video titles
Option A: Docker Run (Simple)
docker run -d \
--name=echotube \
-e ET_CHANNEL_IDS=UCexample1,UCexample2 \
-e ET_KEYWORDS=minecraft,gaming,tutorial \
-e ET_DISCORD_WEBHOOK_URLS=https://discord.com/api/webhooks/... \
-v ./cache:/app/cache \
richardthornton/echotube:latestOption B: Docker Compose (Recommended)
# Get the template files
curl -O https://raw.githubusercontent.com/richardthornton/echotube/main/docker-compose.yml
curl -O https://raw.githubusercontent.com/richardthornton/echotube/main/.env.example
# Set up your configuration
cp .env.example .env
# Edit .env with your settings
# Start EchoTube
docker-compose up -d| Variable | Description | Example |
|---|---|---|
ET_DISCORD_WEBHOOK_URLS |
Discord webhook URLs - comma-separated for multiple servers (How to create) | https://discord.com/api/webhooks/... or https://discord.com/api/webhooks/url1,https://discord.com/api/webhooks/url2 |
ET_KEYWORDS |
Comma-separated search terms | minecraft,gaming,tutorial |
| Variable | Description | Example |
|---|---|---|
ET_CHANNEL_IDS |
Comma-separated YouTube channel IDs | UCexample1,UCexample2 |
ET_PLAYLIST_IDS |
Comma-separated YouTube playlist IDs | PLexample1,PLexample2 |
| Variable | Default | Description |
|---|---|---|
ET_MATCH_TYPE |
any |
any (match any keyword) or all (match all keywords) |
ET_POLL_INTERVAL_SECONDS |
300 |
Poll frequency in seconds (minimum: 60) |
ET_LOG_LEVEL |
INFO |
Log level: DEBUG, INFO, WARN, ERROR |
ET_CACHE_FILE |
memory-only | Path for persistent video cache |
ET_TEST_MODE |
false |
Set to true to test without posting to Discord |
ET_DEVELOPMENT_MODE |
false |
Set to true to post only one video per source |
EchoTube creates beautiful, minimal Discord notifications featuring:
- Channel Name - Clickable link to the YouTube channel
- Video Title - Clickable link to the YouTube video
- Large Thumbnail - High-resolution video preview (1280x720)
- YouTube Red Color - Clean, recognizable branding
What's NOT included: dates, footers, source info, or any clutter - just pure video content.
- Go to the YouTube channel
- Look at the URL:
youtube.com/channel/UCexampleoryoutube.com/c/channelname - If URL shows
/c/channelname, view page source and search for"channelId":"UC
- Go to the YouTube playlist
- Look at the URL:
youtube.com/playlist?list=PLexample - Copy everything after
list=
- Gaming Communities: Monitor favorite streamers and post to multiple Discord servers
- Educational Content: Track programming tutorials and share across learning communities
- Content Curation: Automatically share relevant videos in multiple community Discord servers
- Development Updates: Get notified about software releases in both team and public servers
- Entertainment: Follow content creators and cross-post to different interest-based servers
- RSS Feed Limitation: YouTube RSS feeds only show the 25 most recent videos
- Title-Only Matching: Only matches video titles (descriptions/tags not available via RSS)
- Public Content Only: No access to private playlists or unlisted content
- Duplicate Prevention: Monitoring both channels AND their playlists may cause duplicate notifications
- Rate Limiting: Discord webhooks are rate-limited to prevent spam
Perfect for validating your configuration:
ET_TEST_MODE=true docker-compose up echotube-testPosts only one video per source for testing:
ET_DEVELOPMENT_MODE=true docker-compose up echotube-devBuild from source for development:
git clone https://github.com/richardthornton/echotube.git
cd echotube
docker build -t echotube:custom .Something not working? Here's how to troubleshoot:
- Always test first: Use
ET_TEST_MODE=trueto validate your setup safely - Check the basics: Verify your Discord webhook URLs are active and YouTube channel IDs are correct
- Look at logs: Run
docker logs echotubeto see what's happening (logs show webhook-specific success/failures) - Common issues: Keywords are case-insensitive, RSS feeds only show 25 recent videos, and invalid webhook URLs will cause posting failures
Still stuck? Open an issue and we'll help you out!
If EchoTube saves you time and makes your Discord server better, consider buying me a coffee! Your support helps keep this project maintained and improves it for everyone.
Every contribution, no matter how small, helps maintain and improve EchoTube for the community. Thank you! 🙏
Want to make EchoTube even better? We'd love your help!
- Fork the repository
- Create a feature branch
- Make your improvements
- Test with
ET_TEST_MODE=true - Submit a pull request
See our Contributing Guide for more details.
Docker Hub (Recommended)
docker pull richardthornton/echotube:latestGitHub Container Registry
docker pull ghcr.io/richardthornton/echotube:latest From Source
git clone https://github.com/richardthornton/echotube.git
cd echotube && npm install && npm startMIT License © Richard Thornton - Use it however you want!
Made with ❤️ by Richard Thornton
EchoTube: Clean YouTube notifications for Discord, the way they should be. ✨