Podsync

Podsync - is a simple, free service that lets you listen to any YouTube / Vimeo channels, playlists or user videos in podcast format.

Podcast applications have a rich functionality for content delivery - automatic download of new episodes, remembering last played position, sync between devices and offline listening. This functionality is not available on YouTube and Vimeo. So the aim of Podsync is to make your life easier and enable you to view/listen to content on any device in podcast client.

✨ Features

• Works with YouTube and Vimeo.
• Supports feeds configuration: video/audio, high/low quality, max video height, etc.
• mp3 encoding
• Update scheduler supports cron expressions
• Episodes filtering (match by title, duration).
• Feeds customizations (custom artwork, category, language, etc).
• OPML export.
• Supports episodes cleanup (keep last X episodes).
• Configurable hooks for custom integrations and workflows.
• One-click deployment for AWS.
• Runs on Windows, Mac OS, Linux, and Docker.
• Supports ARM.
• Automatic yt-dlp self update.
• Supports API keys rotation.

📋 Dependencies

If you're running the CLI as binary (e.g. not via Docker), you need to make sure that dependencies are available on your system. Currently, Podsync depends on yt-dlp , ffmpeg, and go.

On Mac you can install those with brew:

brew install yt-dlp ffmpeg go

📖 Documentation

• How to get Vimeo API token
• How to get YouTube API Key
• Podsync on QNAP NAS Guide
• Schedule updates with cron

🌙 Nightly builds

Nightly builds uploaded every midnight from the main branch and available for testing:

$ docker run -it --rm ghcr.io/mxpv/podsync:nightly

🔑 Access tokens

In order to query YouTube or Vimeo API you have to obtain an API token first.

• How to get YouTube API key
• Generate an access token for Vimeo

⚙️ Configuration

You need to create a configuration file (for instance config.toml) and specify the list of feeds that you're going to host. See config.toml.example for all possible configuration keys available in Podsync.

Minimal configuration would look like this:

[server]
port = 8080

[storage]
  [storage.local]
  # Don't change if you run podsync via docker
  data_dir = "/app/data/"

[tokens]
youtube = "PASTE YOUR API KEY HERE" # See config.toml.example for environment variables

[feeds]
    [feeds.ID1]
    url = "https://www.youtube.com/channel/UCxC5Ls6DwqV0e-CYcAKkExQ"

If you want to hide Podsync behind reverse proxy like nginx, you can use hostname field:

[server]
port = 8080
hostname = "https://my.test.host:4443"

[feeds]
  [feeds.ID1]
  ...

Server will be accessible from http://localhost:8080, but episode links will point to https://my.test.host:4443/ID1/...

🌍 Environment Variables

Podsync supports the following environment variables for configuration and API keys:

🚀 How to run

Build and run as binary:

Make sure you have created the file config.toml. Also note the location of the data_dir. Depending on the operating system, you may have to choose a different location since /app/data might be not writable.

$ git clone https://github.com/mxpv/podsync
$ cd podsync
$ make
$ ./bin/podsync --config config.toml

🗂️ One-time filename migration

If you changed filename_template and want to migrate already-downloaded files:

$ ./bin/podsync --config config.toml --migrate-filenames

Preview only (no writes):

$ ./bin/podsync --config config.toml --migrate-filenames --migrate-filenames-dry-run

Note: when storage.type = "s3", only dry-run mode is supported currently. Non-dry-run migration requires readable legacy files and should be run against local storage.

🐛 How to debug

Use the editor Visual Studio Code and install the official Go extension. Afterwards you can execute "Run & Debug" ▶︎ "Debug Podsync" to debug the application. The required configuration is already prepared (see .vscode/launch.json).

🐳 Run via Docker:

$ docker pull ghcr.io/mxpv/podsync:latest
$ docker run \
    -p 8080:8080 \
    -v $(pwd)/data:/app/data/ \
    -v $(pwd)/db:/app/db/ \
    -v $(pwd)/config.toml:/app/config.toml \
    ghcr.io/mxpv/podsync:latest

🐳 Run via Docker Compose:

$ cat docker-compose.yml
services:
  podsync:
    image: ghcr.io/mxpv/podsync
    container_name: podsync
    volumes:
      - ./data:/app/data/
      - ./db:/app/db/
      - ./config.toml:/app/config.toml
    ports:
      - 8080:8080

$ docker compose up

📦 How to make a release

Just push a git tag. CI will do the rest.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Fork Note

This fork adds the following features while maintaining compatibility with upstream mxpv/podsync:

• Configurable filename_template for downloaded media and RSS enclosure paths
• Optional one-time filename migration CLI (--migrate-filenames, --migrate-filenames-dry-run)