Vodular

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

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 the tool for the first time to generate a starter configuration file:

$ vodular
New config file created (config.toml). Please edit this file before running again!

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
Directory successfully initialised. Be sure to update metadata.toml before uploading!

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

5. Upload a VOD (Optionally, delete the redundant full VOD export afterwards):

$ vodular --deleteAfter /path/to/vod

NOTE: On first run, you will be prompted to sign in to YouTube with the channel you wish to upload to. To sign 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) Additional tags to add to this VOD's metadata.
tags = ['livestream', 'VOD']
# (Optional) Footage directory override, for more complex directory structures.
footage_dir = 'footage'
# Set to `true` by the tool when the VOD has been uploaded successfully.
# Prevents future uploads unless `--force` is used.
uploaded = 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