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

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!
```sh
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 `--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) 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](https://pkg.go.dev/text/template) 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](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*