103 lines
4.1 KiB
Markdown
103 lines
4.1 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, 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*
|