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!

2. Edit 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#

Template files can be created at templates/title.txt, template/description.txt, and templates/tags.txt respectively. These files can use Go's text template format to customise VOD metadata on upload.

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