arimelody.space
Helper tool for stitching together livestream VOD segments and uploading them to YouTube!
1# Vodular
2This tool stitches together livestream VOD segments (in `.mkv`format) and automatically uploads them to YouTube, complete with customisable metadata such as titles, descriptions, and tags.
3
4I 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!
5
6## Quick Jump
7- [Basic Usage](#basic-usage)
8- [VOD Metadata](#vod-metadata)
9- [Templates](#templates)
10
11## Basic usage
121. Run the tool for the first time to generate a starter configuration file:
13```sh
14$ vodular
15New config file created (config.toml). Please edit this file before running again!
16```
17The directory which holds your configuration file and templates varies,
18depending on platform:
19- **Linux:** `~/.config/vodular/templates`
20- **macOS:** `~/Library/Application Support/vodular/templates`
21- **Windows:** `%AppData%/vodular/templates`
22
232. Edit your configuration file as necessary (You will need to create a [YouTube Data API v3](https://developers.google.com/youtube/v3) service and provide its credentials here).
24**IMPORTANT:** `config.toml` contains very sensitive credentials. Do not share this file with anyone.
25
263. Initialise a VOD directory:
27```sh
28$ vodular --init /path/to/vod
29Directory successfully initialised. Be sure to update metadata.toml before uploading!
30```
31
324. Modify your newly-created `metadata.toml` to your liking.
33
345. Upload a VOD (Optionally, delete the redundant full VOD export afterwards):
35```sh
36$ vodular --deleteAfter /path/to/vod
37```
38
39**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`.
40
41## VOD Metadata
42When `--init`ialising a directory, a `metadata.toml` file is created. This is a
43plain-text file providing some simple options to customise uploads per
44directory. See this example file with additional comments:
45
46```toml
47# The title of the stream
48title = 'Untitled Stream'
49# (Optional) The part of an episodic stream. 0 assumes this is not episodic.
50part = 0
51# The date of the stream
52date = '2026-01-28'
53# (Optional) Additional tags to add to this VOD's metadata.
54tags = ['livestream', 'VOD']
55# (Optional) Footage directory override, for more complex directory structures.
56footage_dir = 'footage'
57# Set to `true` by the tool when the VOD has been uploaded successfully.
58# Prevents future uploads unless `--force` is used.
59uploaded = false
60
61# (Optional) Category details, for additional credits.
62[category]
63# Game titles and generic categories are applicable here, i.e. "Minecraft", "Art", etc.
64name = 'This Thing'
65# Valid types: gaming, other (default: other)
66type = 'other'
67url = 'https://example.org'
68```
69
70## Templates
71There are three template files, `title.txt`, `description.txt`, and `tags.txt`,
72which can be created in `/path/to/vodular/templates`. These templates can be
73created and tweaked to customise your VOD metadata on upload. They are enhanced
74with Go's [template format](https://pkg.go.dev/text/template) to inject
75information provided in `metadata.toml`, and other neat functionality!
76
77You can use the following data in templates:
78- **`.Title`:** The title of the stream.
79- **`.Date`:** The date of the stream.
80- **`.Part`:** The part number of the stream (Good for episodic streams!)
81- **`.Category`:** Stream category details. (**NOTE:** Wrap usage in `{{if .Category}}` to ensure this field exists first!)
82- **`.Category.Name`:** The stream category name (Game titles and generic categories are applicable here, i.e. "Minecraft", "Art", etc.)
83- **`.Category.Type`:** At this time, should only ever be `"gaming"` or `"other"`.
84- **`.Category.Url`:** A URL relevant to the category. Use this to direct viewers to what you were checking out!
85
86Some helper functions are also provided:
87- **`FormatTime <time> <format>`:** Format the provided time (`.Date`) according to a [Go time format](https://go.dev/src/time/format.go).
88- **`ToLower <text>`:** Convert `text` to all-lowercase.
89- **`ToUpper <text>`:** Convert `text` to all-uppercase.
90
91For reference, you can find my personal templates [here](templates/). These should prove helpful if you aren't already familiar with Go's templating language!
92
93*made with <3 by ari melody, 2026*