93 lines
4.2 KiB
Markdown
93 lines
4.2 KiB
Markdown
# 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!
|
||
```
|
||
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
|
||
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
|
||
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*
|