Vodular

This tool stitches together livestream VOD segments (in .mkv format) and automatically uploads them to YouTube, complete with customisable metadata such as titles, descriptions, tags, and a thumbnail!

I built this to greatly simplify the process of getting my full-quality livestream VODs onto YouTube, and I'm open-sourcing it in the hopes that it helps someone else with their workflow. As such, personal forks are welcome and encouraged!

Quick Jump

• Basic Usage
• VOD Metadata
• Templates

Basic usage

1. Run vodular for the first time to generate a starter configuration file:

The directory which holds your configuration file and templates varies, depending on platform:

• Linux: ~/.config/vodular/templates
• macOS: ~/Library/Application Support/vodular/templates
• Windows: %AppData%/vodular/templates

2. Edit your configuration file as necessary (You will need to create a YouTube Data API v3 service and provide its credentials here). IMPORTANT: config.toml contains very sensitive credentials. Do not share this file with anyone.

3. Initialise a VOD directory:

vodular --init /path/to/vod

This directory should contain:

• A metadata.toml file
• Your footage files, either at the root of the directory or in a specified subdirectory
• Your thumbnail, specifically named thumbnail.png

4. Modify your newly-created metadata.toml to your liking.

5. Upload a VOD!

vodular /path/to/vod

NOTE: On first run, you will be prompted to log into YouTube with the channel you wish to upload to. To log out, simply run vodular --logout.

VOD Metadata

When --initialising a directory, a metadata.toml file is created. This is a plain-text file providing some simple options to customise uploads per directory. See this example file with additional comments:

# The title of the stream
title = 'Untitled Stream'
# (Optional) The part of an episodic stream. 0 assumes this is not episodic.
part = 0
# The date of the stream
date = '2026-01-28'
# (Optional) VOD-specific tags. Added to global tags template.
tags = ['livestream', 'VOD']
# (Optional) Footage directory override, for more complex directory structures.
footage_dir = 'footage'
# On successful upload, updated to a URL to the video.
upload_url = false

# (Optional) Category details, for additional credits.
[category]
# Game titles and generic categories are applicable here, i.e. "Minecraft", "Art", etc.
name = 'This Thing'
# Valid types: gaming, other (default: other)
type = 'other'
url = 'https://example.org'

Templates

There are three template files, title.txt, description.txt, and tags.txt, which can be created in /path/to/vodular/templates. These templates can be created and tweaked to customise your VOD metadata on upload. They are enhanced with Go's template format to inject information provided in metadata.toml, and other neat functionality!

You can use the following data in templates:

• .Title: The title of the stream.
• .Date: The date of the stream.
• .Part: The part number of the stream (Good for episodic streams!)
• .Category: Stream category details. (NOTE: Wrap usage in {{if .Category}} to ensure this field exists first!)
• .Category.Name: The stream category name (Game titles and generic categories are applicable here, i.e. "Minecraft", "Art", etc.)
• .Category.Type: At this time, should only ever be "gaming" or "other".
• .Category.Url: A URL relevant to the category. Use this to direct viewers to what you were checking out!

Some helper functions are also provided:

• FormatTime <time> <format>: Format the provided time (.Date) according to a Go time format.
• ToLower <text>: Convert text to all-lowercase.
• ToUpper <text>: Convert text to all-uppercase.

For reference, you can find my personal templates here. These should prove helpful if you aren't already familiar with Go's templating language!

made with <3 by ari melody, 2026