podvid

README

podvid

Turn any video into a podcast episode on your own S3 storage.

---

podvid downloads videos from any platform supported by yt-dlp (YouTube, VK Video, RuTube, and 1800+ others), extracts the audio as MP3, uploads it to an S3-compatible storage, and maintains a valid RSS feed so you can subscribe in any podcast app.

Built for listening to video bloggers on an iPod Nano 7, but works with any podcast client.

Features

• TUI mode — interactive terminal UI (Bubble Tea), just run podvid
• CLI mode — scriptable commands for automation
• MCP mode — expose podvid to AI agents over the Model Context Protocol (podvid mcp)
• Auto-provisioning — installs yt-dlp automatically via Python venv if not found in PATH
• S3-compatible — works with AWS S3, Yandex Object Storage, MinIO, Selectel, etc.
• iTunes RSS — generates valid RSS 2.0 with iTunes extensions (cover art, duration, per-episode thumbnails)
• Episode metadata — pulls title, description, thumbnail, duration and publish date from the source

Requirements

• Go 1.21+
• ffmpeg in PATH
• Python 3 (for auto-installing yt-dlp) or yt-dlp in PATH

Install

go install github.com/grigory51/podvid/cmd/podvid@latest

Or build from source:

git clone https://github.com/grigory51/podvid.git
cd podvid
go build ./cmd/podvid/

Quick start

# 1. Configure S3 credentials
podvid config init

# 2. Create a podcast
podvid podcast create --name "My Podcast"

# 3. Add an episode from any video URL
podvid episode add my-podcast https://vkvideo.ru/video-1980_456246417

# 4. Subscribe to the feed URL in your podcast app

Or just run podvid for the interactive TUI.

CLI reference

podvid                                        # Launch TUI
podvid config init                            # Interactive S3 setup
podvid config show                            # Show current config

podvid podcast create --name "..." [--description "..."] [--cover image.jpg]
podvid podcast list
podvid podcast edit <slug> [--name "..."] [--description "..."] [--cover image.jpg]
podvid podcast delete <slug>

podvid episode add <podcast-slug> <url>
podvid episode list <podcast-slug>
podvid episode edit <podcast-slug> <episode-id> [--title "..."] [--description "..."]
podvid episode delete <podcast-slug> <episode-id>

MCP mode

podvid mcp starts a Model Context Protocol server over stdio, letting an agent (e.g. Claude) perform the same operations you do in the TUI or CLI. It reads the same config file and S3 credentials.

Register it with an MCP client. For Claude Code:

claude mcp add podvid -- podvid mcp

Or in a client config (mcpServers):

{
  "mcpServers": {
    "podvid": {
      "command": "podvid",
      "args": ["mcp"]
    }
  }
}

Exposed tools:

Tool	Description
podcast_list	List all podcasts
podcast_get	Get one podcast by slug
podcast_create	Create a podcast
podcast_edit	Edit name/description
episode_list	List a podcast's episodes
episode_add	Download a video URL and add it as an episode
episode_edit	Edit episode title/description
config_show	Show current config (secrets masked)

Destructive operations (deleting podcasts/episodes, removing covers) are intentionally not exposed over MCP. Use the TUI or CLI for those.

Configuration

Config file: ~/.config/podvid/config.yaml

s3:
  endpoint: "https://storage.yandexcloud.net"
  region: "ru-central1"
  bucket: "my-podcasts"
  access_key: "..."
  secret_key: "..."
  public_base_url: "https://storage.yandexcloud.net/my-podcasts"

audio:
  bitrate: "192k"

Override any value via environment variables (PODVID_S3_BUCKET, PODVID_S3_ACCESS_KEY, ...) or CLI flags.

How it works

1. Downloads video via yt-dlp
2. Extracts audio track, converts to MP3 via ffmpeg
3. Uploads MP3 + episode thumbnail to S3
4. Updates the RSS feed (XML) on the same S3 bucket
5. Podcast app fetches the feed and shows new episodes

License

MIT