Getting started

Download the repository with:

git clone --recursive https://github.com/VideoTagger/VideoTagger

If the repository was cloned non-recursively run:

git submodule update --init

Build Requirements

• Python 3.12+ (tested with 3.12.6 and 3.13.0)
• Visual Studio 2022 (on Windows)

[!Important] Both Linux and macOS require SDL2 version 2.0.17 or later to build properly. Windows comes with prebuilt binaries.

Windows - Visual Studio

Generate project files with:

scripts/win-gen-projects.cmd

Build the projects by opening the Visual Studio solution file and building with desired configuration.

Linux - Makefile

Install Required packages

build-essential pkg-config libsdl2-dev libavcodec-dev libavformat-dev libswscale-dev python3-dev libgtk-3-dev libglib2.0-dev libgtk2.0-dev libssl-dev

Generate project files with:

chmod +x ./scripts/linux-gen-projects.sh && ./scripts/linux-gen-projects.sh

Build the projects by running:

make config=<BUILD_CONFIG>

Replace <BUILD_CONFIG> with one of:

• debug_x86_64
• release_x86_64
• shipping_x86_64

Xcode (macOS)

[!Warning] Building on macOS is untested

Generate project files with:

scripts/macos-gen-projects.sh

Build the projects by opening the Xcode project file and building with desired configuration.

Third party libraries

• SDL2
• ImGui
• ImGuizmo
• Native File Dialog Extended
• fmt
• Nlohmann Json
• utf8.h
• pybind11
• FFmpeg
• cpp-httplib
• OpenSSL

License

This software is licensed under the MIT License.

This software uses LGPL-licensed libraries from the FFmpeg project.

FFmpeg is an open-source framework licensed under the GNU Lesser General Public License (LGPL) version 2.1 or later. However, FFmpeg incorporates several optional parts and optimizations that are covered by the GNU General Public License (GPL) version 2 or later. If those parts get used the GPL applies to all of FFmpeg.

For more information regarding FFmpeg license and legal considerations see https://www.ffmpeg.org/legal.html.

Similiar Apps

First Project

To create a new project you will need to press the New Project button while in the Project Selector window. After that project configuration popup will appear and you will be prompted to set:

• Project name
• Project file location

After confirming the project creation with Create button, your newly created project will be automatically opened.

Importing Videos

In order to import videos to your project you will need to select File > Import Videos on the menubar. After that a dialog window will appear and prompt you to select video files (one or more).

Videos imported via this option will be stored in the project file as relative filepaths, which gives you the ability to share your project with others.

Importing Projects

In order to import an existing project you will need to press the Add Existing Project button while in Project Selector window. This button can be found under the New Project button. After that you will be prompted to select .vtproj file containing the project you wish to import.

Imported project will be added to the project list.

Video Management

Videos are organized into video groups which are displayed in the Video Group Browser. Importing a video will automatically create a group with the same name as the video. Clicking the plus button will allow you to create a new video group. Videos can be added to a group by dragging a video from the Video Browser onto a group in the Video Group Browser.

Tag Management

All tag related operations such as adding, modifying and removing a tag can be done via the Tag Manager window.

All tags shown there are stored in the project file and can be used on the Timeline window to create segments or timestamps. To learn more about the Timeline head over to Video Timeline page.

Tagging Basics

In order to start tagging a video or a group of videos you need to have at least one tag (see Tag Management) and have a video group currently playing (see Video Management). Once that's all setup click the plus button on the timeline and select the tags you want to use. Next, right-click on the timeline. A menu will appear with the following options:

• Add timestamp
• Add segment
• Add timestamp at marker
• Add segment at marker
• Start segment at marker
• End segment at marker

After selecting one of the first four options, a popup will appear. If you selected one of the options with "timestamp", you'll be able to select the time at which the timestamp will be created. If you selected one of the options with "segment", you'll be able to select where the segment will start and end. Clicking "OK" will create the timestamp or segment.

Selecting "Start segment at marker" won't have immediately visible effects. However, once you click "End segment at marker", a popup will appear, showing the start and end times set to the positions of the time marker when "Start segment at marker" and "End segment at marker" were selected, respectively. If you click "Start segment at marker" and then "End segment at marker" without moving the time marker, a timestamp will be created instead of a segment.

If you try to create a timestamp/segment which would overlap an already existing timestamp/segment a popup will appear asking whether to merge the segments. Selecting "Yes" will merge the segment you want to create and the existing segment, while selecting "No" will cancel the timestamp/segment creation.

Video Timeline

Timeline editing is only available when a video group is currently playing. The timeline is used to tag the active group with timestamps and segments. In order to start tagging, you need to enable the tags you want to show up on the timeline.

Exporting Tagging Data

In order to export tagging data of the active video group (see Video Management for how to use video groups) select the Export Segments option from the Import/Export list in the File menu.

The tagging data in saved in a JSON file with the following structure:

{
    "version": "int",

    "groups": [
        {
            "name": "string",
            "id": "string",

            "videos": [
                "video-obj" // one or more
            ],

            "tags": [
                "string" // tag name, one or more
            ],

            "segments": {
                "video-id": [ // 'video-id' is one of the ids from the videos list. Every video from the videos list must be represented
                    {
                        "tag": "tag-name", // 'tag-name' is one of the tags from the tags list
                        "segments": [
                            "segment-obj", // zero or more
                            "timestamp-obj"  // zero or more
                        ]
                    }
                ]
            }
        }
    ]
}

Object definitions:

"video-obj": {
    "name": "string",
    "id": "string"
}

"segment-obj": {
    "start": "time", // 'time' is a string representing time in the format hh:mm:ss
    "end": "time" // 'time' is a string representing time in the format hh:mm:ss
}

"timestamp-obj":{
    "timestamp": "time" // 'time' is a string representing time in the format hh:mm:ss
}

Example

{
	"version": 1,
	"groups": [
		{
			"name": "Steamboat Willie",
			"id": "13470171703746230198",
			"videos": [
				{
					"name": "Steamboat Willie.mp4",
					"id": "4839065930439805551"
				}
			],
			"tags": [
				"Tag1",
				"Tag2",
				"Tag3",
				"Tag4"
			],
			"segments": {
				"4839065930439805551": [
					{
						"tag": "Tag1",
						"segments": [
							{
								"start": "00:00:04",
								"end": "00:00:08"
							},
							{
								"timestamp": "00:00:16"
							}
						]
					},
					{
						"tag": "Tag2",
						"segments": [
							{
								"start": "00:00:02",
								"end": "00:00:05"
							},
							{
								"start": "00:00:11",
								"end": "00:00:15"
							},
							{
								"timestamp": "00:00:19"
							}
						]
					},
					{
						"tag": "Tag3",
						"segments": [
							{
								"start": "00:00:07",
								"end": "00:00:10"
							},
							{
								"start": "00:00:25",
								"end": "00:00:33"
							}
						]
					},
					{
						"tag": "Tag4",
						"segments": [
							{
								"timestamp": "00:00:19"
							},
							{
								"start": "00:00:36",
								"end": "00:00:46"
							}
						]
					}
				]
			}
		}
	]
}

Keybind Categories

Keybinds are split into two categories:

• Application Keybinds
• Project Keybinds

The main difference between them is the fact that Application Keybinds are shared between projects and Project Keybinds are stored in the project file.

First Keybind

To add a keybind to your project, select Tools > Options > Project Settings > Keybinds from the menubar and press the Add Keybind button.

When the popup window opens you need to:

• Assign keybind's name
• Press your desired key combination
• Assign an action that should happen when the keybind is pressed

Some keybind actions have additional attributes, to learn more about them head over to Keybind Actions

After configuring your keybind, press the Save button which will store the keybind in your project file.

Keybind Actions

Keybinds support multiple actions, where each one of them can have multiple attributes. Available actions:

• None
• Insert Timestamp
  • Tag Name: Timestamp inserted with this action will have this tag name, unless you've selected Ask Later. Then a popup will appear prompting you to choose the tag you want to insert at the current timeline marker position, additionaly you can tweak the insertion point
• Start/End Segment
  • Tag Name: This attribute has the same behaviour as in Insert Timestamp action.
  • Type: This attribute represents what should happen when the keybind is pressed. It could be Auto, Start or End where:
    • Auto will start the segment if it wasn't started yet, or end it otherwise
    • Start will only start the segment if it wasn't started before
    • End will only end the segment if it was started before