https://github.com/bcopy/advent-podcast
A configurable private podcast server, perfect for advent calendars, daily music releases, or any time-based audio content.
https://github.com/bcopy/advent-podcast
glitch-com nodejs podcasting server
Last synced: 7 months ago
JSON representation
A configurable private podcast server, perfect for advent calendars, daily music releases, or any time-based audio content.
- Host: GitHub
- URL: https://github.com/bcopy/advent-podcast
- Owner: bcopy
- License: gpl-3.0
- Created: 2024-11-23T11:36:02.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2024-11-24T12:06:14.000Z (11 months ago)
- Last Synced: 2025-01-28T01:44:24.688Z (8 months ago)
- Topics: glitch-com, nodejs, podcasting, server
- Language: JavaScript
- Homepage:
- Size: 43.9 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 🎄 Advent Podcast Server 🎧
Create your own private podcast feed with scheduled episodes! Perfect for advent calendars, daily music releases, or any time-based audio content. Each audio file is released based on its filename date - it's like magic! ✨
## 🚀 Quick Start on self-hosted server
1. Setup your Node JS environment ( npm install )
2. Set your secret token in `.env`:
```
SECRET_TOKEN=your-super-secret-string
```
3. Upload your MP3 files to `data/audio` with this naming pattern:
```
YYYY-MM-DD_Episode_Title.mp3
For example:
2024-12-01_First_Day_Of_Christmas.mp3
2024-12-24_Christmas_Eve_Special.mp3
```
4. Populate the ``data/metadata.yml`` file (c.f. example below)
🎉 That's it! Your podcast is ready at:
```
https://your-project-name.com/feed.xml?token=your-super-secret-string
```
## 🚀 Quick Start on Glitch.com
1. Import this Github project on Glitch
2. Set your secret token in `.env`:
```
SECRET_TOKEN=your-super-secret-string
```
3. Upload your MP3 files to Glitch assets with this naming pattern:
```
YYYY-MM-DD_Episode_Title.mp3
For example:
2024-12-01_First_Day_Of_Christmas.mp3
2024-12-24_Christmas_Eve_Special.mp3
```
4. Populate the ``data/metadata.yml`` file (c.f. example below) - the file name has to match the assets.
🎉 That's it! Your podcast is ready at:
```
https://your-project-name.glitch.me/feed.xml?token=your-super-secret-string
```
## 🎸 Adding Episode Details (Optional)
Want to add descriptions, artist info, or duration? Create `data/metadata.yml`:
```yaml
podcast:
title: "My Awesome Advent Calendar"
description: "24 days of musical surprises"
author: "Santa's Little Helper"
image: "https://your.host.com/path/to/my-podcast-image.png"
episodes:
"2024-12-01_First_Day_Of_Christmas.mp3":
title: "First Day of Christmas"
description: "A partridge in a pear tree 🎵"
author: "The Christmas Band"
duration: "3:45"
image: "https://your.host.com/path/to/my-episode1-image.png"
"2024-12-24_Christmas_Eve_Special.ogg":
title: "Christmas Eve Special"
description: "The grand finale! 🎄"
author: "Santa & The Reindeer"
duration: "5:30"
image: "https://your.host.com/path/to/my-episode2-image.png"
categories:
- Holiday
- Jazz
```
## 🎵 Supported Audio Formats
Upload your audio files in any of these formats:
- `.mp3` - MPEG Audio Layer III
```
2024-12-01_First_Day.mp3
```
- `.m4a` - AAC Audio
```
2024-12-02_Second_Day.m4a
```
- `.opus` - Opus Audio (better quality at lower bitrates!)
```
2024-12-03_Third_Day.opus
2024-12-04_Fourth_Day.ogg # Opus in Ogg container
2024-12-05_Fifth_Day.mka # Opus in Matroska container
```
### 🎧 Format Tips
- **MP3**: Best compatibility with all podcast players
- **M4A**: Better quality than MP3 at the same size
- **Opus**: Best quality-to-size ratio, but check your target podcast app for compatibility
### 🔍 Compatibility Notes
- Apple Podcasts: Supports MP3 and M4A
- Pocket Casts: Supports all formats
- Overcast: Supports MP3 and M4A
- Web browsers: Support varies (check [caniuse.com](https://caniuse.com/?search=opus) for Opus support)
## 📱 Adding to Your Podcast App
1. Copy your feed URL:
```
https://your-project-name.glitch.me/feed.xml?token=your-super-secret-string
```
2. Add it to your favorite podcast app:
- Apple Podcasts: Library → Add a Show → Add URL
- Overcast: + → Add URL
- Pocket Casts: Search → Add URL
- Spotify: Coming soon! 🤞 (accepting Github PRs 🤝)
## 🔍 Useful Endpoints
- Check your episodes:
```
/episodes?token=your-super-secret-string
```
- Direct MP3 access (⚠️ Not supported on Glitch.com, assets are stored separately) :
```
/audio/YYYY-MM-DD_Episode_Title.mp3?token=your-super-secret-string
```
## 💡 Pro Tips
- Episodes are released at midnight based on the date in the filename
- Files without dates are always available
- Keep your token secret - it's your podcast's VIP pass! 🎟️
- Store files in `data/audio` - they won't be included in remixes
- The free Glitch plan has a 200MB storage limit - perfect for an advent calendar!
## 🎯 Coming Soon
- [ ] Cover art support
- [ ] Web interface for metadata editing (accepting Github PRs 🤝)
- [ ] Automatic file cleanup (accepting Github PRs 🤝)
- [ ] Episode analytics (accepting Github PRs 🤝)
## 🐛 Troubleshooting
Nothing playing? Check that:
1. Your files are in `data/audio`
2. Filenames follow the `YYYY-MM-DD_Title.mp3` format
3. The release date has arrived
4. Your token is correct
## 🤝 Contributing
Found a bug? Want to add a feature? PRs welcome!
## 📜 License
MIT - Go wild! 🎉
---
*P.S. If you make something cool with this, let me know! I'd love to hear about it!* 🎧