Configuration

By default, VodBot loads a JSON formatted configuration file located in a folder dedicated to VodBot in the user's home directory. VodBot handles a lot of functions with default values taken from this config file. A config file and all the necessary directories are created after running vodbot init, which you can read about here. An example is provided at the bottom of the page.

Fields

These are all the fields that can be used and configured in the config file, and what they are. If you need an example of a full configuration file, there is one provided below.

Channels

This is a list of JSON objects that each contain the following elements:

username: a string, the twitch username of the channel to pull VODs, Clips, and chat logs from, specifically the string at the end of their page URL.
save_vods: a boolean, determines whether VODs will be pulled for this channel.
save_clips: a boolean, determines whether Clips will be pulled for this channel.
save_chat: a boolean, determines whether chat logs will be pulled for this channel.

Pull

This section is related to the pulling of content from Twitch, specifically how the content is pulled and what content is pulled.

save_vods: a boolean, a master toggle for whether VODs will be pulled for any channel. Defaults to true.
save_clips: a boolean, a master toggle for whether Clips will be pulled for any channel. Defaults to true.
save_chat: a boolean, a master toggle for whether chat logs will be pulled for any channel. Defaults to true.
gql_client: a string, controls the client ID for the GQL API calls under the hood. Do not change unless you know what you're doing. Defaults to "kd1unb4b3q4t58fwlpcbzcbnm76a8fp"[^1].
max_workers: an integer, number of threads that can concurrently work to download files from Twitch. Defaults to the number of cores on the machine (or 1 in cases where that can't be measured).
chunk_size: an integer, number of bytes to stream-write to temporary video files at a time. Defaults to 1024 bytes.
connection_retries: an integer, how many times the download connection should be retried before giving up. Defaults to 5 retries.
connection_timeout: a float, seconds before the download connection should time out and should be tried again. Defaults to 5 seconds.

Chat

When possible, VodBot will add chat logs from the stream to the video as subtitles in a separate file (or uploaded to YouTube with the video).

export_format: a string, the format that the subtitles will be exported as when exporting videos. Can be "raw" or "YTT". Default is "YTT".
message_display_time: an integer, determines how long in seconds chat messages stay on screen as subtitles. Default is 10.
randomize_uncolored_names: a boolean, toggles whether uncolored chat members (white) get a random color for the exported chat logs. Default is true.
ytt_align: a string, sets how the chat log captions are aligned on YouTube. Can be "left", "right", or "center". Default is "left".
ytt_anchor: an integer, sets the anchor point (origin/offset point) for the chat log captions. Can be any integer from 0 to 8 inclusive. 0 is top left, 1 is top center, 2 is top right, 3 is center left, 4 is true center, 5 is center right, 6 is bottom left, 7 is bottom center, and 8 is bottom right. Default is 6.
ytt_position_x: an integer, sets the position on the x axis. Can be any integer 0 to 100 inclusive. 0 is toward the left, 100 is toward the right. Default is 0.
ytt_position_y: an integer, sets the position on the y axis. Can be any integer 0 to 100 inclusive. 0 is toward the bottom, 100 is toward the top. Default is 100.

Info on the various formats VodBot supports:

The "raw" format is the most basic export VodBot can do of chat logs, it is how VodBot saves chat logs internally. It is not intended to be human readable, you can read more here.
The "YTT" format is also called YouTube Timed Text, and is only unofficially documented here. It supports colors, formatting, and positioning, and is recommended for use with uploading videos.
REMOVED/UNIMPLEMENTED AS OF 1.1. RealText is a markup language style of subtitles, and can be read about here. It generally has the smallest filesize and preserves chat name colors.
REMOVED/UNIMPLEMENTED AS OF 1.1. SAMI (or Synchronized Accessible Media Interchange) is another markup language for subtitles, you can read about it here. It is a useful alternative if RealText is not supported for whatever reason.

Stage

This section is related to the stage function of VodBot, where information on videos is set up and recordered for use with exporting or uploading.

timezone: a string, timezone of the VODs/Clips, used for description formatting. Must be a UTC string like '+0000' or '-0530'.
description_macros: a dictionary of strings that can be formatted with special predefined strings, or other strings from the dictionary. The predefined strings are described below.
- date: The date the stream started, formatted as year/month/day.
- streamer: The streamer who the video is of.
- streamers: A list of all the streamers in the video, created when staged.
- link: The link to the twitch of the streamer.
- links: A space delimited string of all the links of the streamers, created when staged.
delete_on_export: a boolean switch for if staged data should be deleted on a successful export. By default, this value is true.
delete_on_upload: a boolean switch for if staged data should be deleted on a successful upload. By default, this value is true.

Export

Below are settings specific to the vodbot export use case, for exporting staged data to video, caption, and thumbnail files.

ffmpeg_loglevel: a string of logging output level of FFmpeg. Can be "trace", "debug", "verbose", "info", "warning", "error", "fatal", "panic", and "quiet". Default is "warning".
ffmpeg_stderr: a string, a file location of where FFmpeg should pipe its log output (stderr) to. If empty, it will log to "/dev/null". Default is "/dev/null" (or whatever is equivalent on your system).
video_enable: a boolean, a toggle for if videos should be exported from staged data. Default is true.
chat_enable: a boolean, a toggle for if chat logs should be exported from staged data. Default is true.
thumbnail_enable: a boolean, a toggle for if thumbnails should be exported from staged data. Default is true.

Upload

Below are settings specific to the vodbot upload use case. VodBot upload cannot function without the correct client JSON, as described for client_path, which is not provided by VodBot.

chat_enable: a boolean, a toggle for if chat logs should be uploaded from staged data. Default is true.
thumbnail_enable: a boolean, a toggle for if thumbnails should be uploaded from staged data. Default is true.
client_path: a string, the full path to the Google Client OAuth 2.0 JSON, a file with credentials that allow VodBot to use Google's API. Defaults to "~/.vodbot/yt-client.json".
session_path: a string, the full path to where VodBot should store it's session JSON data, a file with credentials that allows VodBot to act on your behalf to upload YouTube content. Defaults to "~/.vodbot/yt-session.json".
chunk_size: an integer, the size of data that VodBot uploads at a time to YouTube. Must be a minimum of 262144, but is recommended to be some larger multiple of this value. Default is 262144.

Thumbnail

This section is related to generating video thumbnails with VodBot.

enable: a boolean, a toggle for whether thumbnails should be asked about when staging data. Defaults to false.
canvas_width: an integer, the width of the canvas that everything gets drawn onto, and thus the width of the finalized thumbnail. Defaults to 1280.
canvas_height: an integer, the height of the canvas that everything gets drawn onto, and thus the height of the finalized thumbnail. Defaults to 720.
screenshot_position: a ThumbnailPosition (see below), position of the screenshot on the canvas.
cover_position: a ThumbnailPosition, position of the cover image on the canvas
cover_filepath: a string, a path relative to the thumbnail directory (see below) of an image.
text_position: a ThumbnailPosition, a position of the text on the canvas.
text_font: a string, a path to a TrueType font. This can be a relative or absolute path. If the path is relative, then locations are checked in this order: 1. Thumbnail directory, 2. System locations, 3. Path relative to execution (not recommended for use).
text_size: an integer, the pointsize of the font to use when printing text to the canvas. Defaults to 48.
head_positions: a list of ThumbnailPosition, each entry is a position of a head on the canvas.
head_order: a list of integers, each entry is dictating what position should be filled first, also dictating the order of layering of heads (example: a list of [0, 2, 1] will place heads at positions 0, 2, and 1 in that order with heads placed first being underneath heads placed last).
heads: a dictionary of ThumbnailIcons (see below), each entry has a key (head name) and ThumbnailIcon object, dictating details of the head icon image. The head name is used for asking about what heads are desired on the canvas during the staging process.
game_position: a ThumbnailPosition, a position of the game icon on the canvas.
games: a dictionary of ThumbnailIcons, each entry has a key (game name) and ThumbnailIcon object, dictating details of the game icon image. The game name is used for asking about what game is desired on the canvas during the staging process.

ThumbnailPosition

This is an object describing how an image should be positioned in a thumbnail.

x: an integer, the absolute position of the image on the x axis, inside the canvas. Defaults to 0.
y: an integer, the absolute position of the image on the y axis, inside the canvas. Defaults to 0.
ox: an integer, the origin point of the image on the x axis. Images are scaled away from this location. Defaults to 0.
oy: an integer, the origin point of the image on the y axis. Images are scaled away from this location. Defaults to 0.
s: an integer, this is the scale of the image in question, gets multiplied by the scale of the icon if relevant. Defaults to 1.

ThumbnailIcon

This is an object describing an image and its properties. These properties are also affected by the position object related to it (example: ox of the icon is added to the ox of the position, scale of the position is multiplied by the scale of the icon, etc).

ox: an integer, the origin point of the image on the x axis. Images are scaled away from this location. Defaults to 0.
oy: an integer, the origin point of the image on the y axis. Images are scaled away from this location. Defaults to 0.
s: an integer, an integer, this is the scale of the image in question, gets multiplied by the scale of the icon if relevant. Defaults to 1.
filepath: a string, a path relative to the thumbnail directory (see below) of an image. Defaults to an empty string.

Webhooks

VodBot can send webhooks to Discord after certain events complete or happen. Settings in this section are used as default for each webhook if not defined in the individual configuration.

pull_vod: a WebhookBase (see below), sending a webhook after a VOD is successfully pulled.
pull_clip: a WebhookBase, sending a webhook after a Clip is successfully pulled.
pull_error: a WebhookBase, sending a webhook after an error has occurred when pulling a video.
pull_job_done: a WebhookBase, sending a webhook after the pull command completes.
export_video: a WebhookBase, sending a webhook after a video is successfully exported.
export_error: a WebhookBase, sending a webhook after an error has occurred when exporting a video.
export_job_done: a WebhookBase, sending a webhook after the export command completes.
upload_video: a WebhookBase, sending a webhook after a video is successfully uploaded.
upload_error: a WebhookBase, sending a webhook after an error has occurred when uploading a video.
upload_job_done: a WebhookBase, sending a webhook after the upload command completes.
vodbot_error: a WebhookBase, sending a webhook after a VodBot encounters an error of any kind and exits early.
enable: a boolean, the master toggle for if webhooks get sent or not. Defaults to false.
message: a string, the default message that's sent alongside whatever context specific information is sent. Defaults to an empty string.
avatar_url: a string, the default URL to an image to use for the webhook message's icon/avatar. Defaults to this icon.
username: a string, the default username to use for the webhook message. Defaults to "VodBot Webhook".
url: a string, the default URL to send the webhook to. Defaults to an empty string.

WebhookBase

Each webhook can be individually configured with the same settings as described above.

enable: a boolean, individual toggle for the webhook. Defaults to true.
message: a string, defaults to an empty string.
avatar_url: a string, defaults to an empty string.
username: a string, defaults to an empty string.
url: a string, defaults to an empty string.

Directories

Places where VodBot will write or read important info to or from. It's recommended the VOD and Clip directories be on a multidisk array for safe keeping, as these files are massive. The stage and temp directory are recommended to be placed in a scratch directory, since files are written and erased from there a lot. The thumbnail directory is for holding useful assets for generating thumbnails VodBot will make the directories if they are not present.

vods: Full path to where VOD files are stored. This should be a safe place!
clips: Full path to where Clip files are stored. This should be a safe place!
temp: Full path to where VodBot will store sections of video during either the download or upload process, as well as other temporary files like chat logs and thumbnails. It is recommended this path is on a scratch storage device like an SSD or ramdisk.
stage: Full path to where VodBot will store text files of StageData, for use in exporting/uploading videos.
thumbnail: Full path to where thumbnail files are stored. This path is prepended to any filepath related to thumbnail files.

Example Config File

{
  "channels": [
    {
      "username": "notquiteapex",
      "save_vods": false,
      "save_clips": true,
      "save_chat": true
    }
  ],
  
  "pull": {
    "save_vods": true,
    "save_clips": true,
    "save_chat": true,

    "gql_client": "kd1unb4b3q4t58fwlpcbzcbnm76a8fp"
  },
  
  "chat": {
    "export_format": "YTT",
    "message_display_time": 10,
    "randomize_uncolored_names": true,
    
    "ytt_align": "left", "ytt_anchor": 6,
    "ytt_position_x": 0, "ytt_position_y": 100
  },
  
  "stage": {
    "timezone": "-0400",
    
    "description_macros": {
      "captions": "Want to see stream chat? ► Enable closed captions w/ 'English - Chat'.",
      "watch": "Watch streams live ► {links}",
      "content": "Watch our content ► https://youtube.friendteam.biz",
      "archive": "Watch past streams ► https://archive.friendteam.biz",
      "discord": "Join the FTI Discord ► https://discord.friendteam.biz",
      "vodbot": "Archived by VodBot ► https://vodbot.friendteam.biz",
      "e": "on {date}.\n\n{captions}\n\n{watch}\n{content}\n{archive}\n{discord}\n\n{vodbot}"
    },
    
    "delete_on_export": true,
    "delete_on_upload": true
  },
  
  "export": {
    "ffmpeg_loglevel": "warning",
    
    "chat_enable": true,
    "video_enable": true,
    "thumbnail_enable": true
  },
  
  "upload": {
    "client_path": "/home/apex/.vodbot/yt-client.json",
    "session_path": "/home/apex/.vodbot/yt-session.json",

    "chunk_size": 262144,
    
    "chat_enable": true,
    "thumbnail_enable": true
  },
  
  "thumbnail": {
    "enable": true,
    
    "canvas_width": 1280, "canvas_height": 720,
    "screenshot_position": { "x":300,"y":0 },
    "cover_position": { "x":0,"y":0 },
    "cover_filepath": "cover.png",
    
    "text_position": { "x":450,"y":10 },
    "text_size": "160",
    "text_font": "Ubuntu-BI.ttf",
    
    "head_order": [ 14,15,16,17,13,12,11,10, 0,1,2,3,4,5,6,7,8,9 ],
    "head_positions": [
      {"x":290, "y":435, "s":2}
    ],
    "heads": {
      "apex":   { "ox": 92,  "oy": 130, "s": 1, "filepath": "heads\\apex.png" },
    },
    
    "game_position": { "x":230, "y":120 },
    "games": {
      "minecraft": { "ox": 213, "oy": 120, "s": 1, "filepath": "games\\mchc.png" },
      "dorffort":  { "ox": 237, "oy": 95,  "filepath": "games\\dorffort.png" },
      "tboi-rep":  { "ox": 231, "oy": 130, "filepath": "games\\tboirep.png" },
      "noita":     { "ox": 172, "oy": 115, "filepath": "games\\noita.png" },
      "celeste":   { "ox": 155, "oy": 125, "filepath": "games\\celeste.png" },
      "openfort":  { "ox": 177, "oy": 125, "filepath": "games\\openfortress.png" }
    }
  },

  "webhooks": {
    "pull_vod": {},
    "pull_clip": {},
    "pull_error": {},
    "pull_job_done": {},
    "export_video": {},
    "export_error": {},
    "export_job_done": {},
    "upload_video": {},
    "upload_error": {},
    "upload_job_done": {},
    "vodbot_error": {
      "avatar_url": "https://cdn.discordapp.com/emojis/1065854983548981311.webp",
      "username": "VodBot ERROR",
      "url": "https://discord.com/api/webhooks/<channel-id>/<webhook-id>"
    },

    "enable": true,
    "message": "",
    "avatar_url": "https://github.com/FriendTeamInc/VodBot/raw/main/assets/logo.png",
    "username": "VodBot",
    "url": "https://discord.com/api/webhooks/<channel-id>/<webhook-id>"
  },
  
  "directories": {
    "vods":      "/mnt/archive/vods",
    "clips":     "/mnt/archive/clips",
    "temp":      "/mnt/scratch/vodbot/temp",
    "stage":     "/home/apex/.vodbot/stage",
    "thumbnail": "/home/apex/.vodbot/thumbnail"
  }
}

I use VodBot on Linux, so these paths are POSIX based, but Windows paths must have all backslashes replaced with double backslashes. (i.e. the path C:\Users\Apex\Desktop\ should be written as "C:\\Users\\Apex\\Desktop\\" in the JSON)

[^1]: NOTE: On or around May 4, 2023, Twitch silently adjusted some permission settings with the old client ID, "kimne78kx3ncx6brgo4mv6wki5h1ko", which prevented it from working in many scenarios. Old versions of VodBot made use of this old client ID and used it as the default. If you are experiencing issues with GQL requests, it is highly recommended that you switch to the new default client ID.

This project is licensed under the MIT license, copyright Logan "NotQuiteApex" Hickok-Dickson. You can read more about the license here.

If you'd like to support this project and the rest of the stuff I do, you can go to my website and select one of the support options, or just click the pink heart Sponsor button at the top of the page.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly