vodular/README.md

# 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, 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](#basic-usage)
- [VOD Metadata](#vod-metadata)
- [Templates](#templates)

## Basic usage
1. Run the tool for the first time to generate a starter configuration file:
```sh
$ 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](https://developers.google.com/youtube/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:
```sh
$ 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):
```sh
$ 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 `--init`ialising 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:

```toml
# 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](https://pkg.go.dev/text/template) 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](https://go.dev/src/time/format.go).
- **`ToLower <text>`:** Convert `text` to all-lowercase.
- **`ToUpper <text>`:** Convert `text` to all-uppercase.

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

*made with <3 by ari melody, 2026*