Annotate User Guide

Documentation for project setup, clip capture, annotation, tracking, pins, presentations, export, and project storage.

The complete workflow

Every feature in one silent, captioned walkthrough of about 13 minutes, from a new project to a finished presentation. Choose a chapter to jump to it.

Chapters

Overview

Annotate is a local application for football video analysis. A project contains imported videos, captured clips, frame pins, annotation data, presentations, exports, caches, and recoverable trash.

Clip annotations are keyframed objects rendered over video. Pin annotations are documents attached to one exact source frame and may include entrance animations. Tracking generates highlight keyframes, while homography provides pitch coordinates for boxes and circles.

Project data is stored in the selected project folder. The app communicates with a Python sidecar on the same computer for video import, tracking, homography, and export operations. Desktop packages include and manage that service; browser development runs it separately.

Clip

A half-open frame range within one imported video.

One exact frame within a clip, with zero or more annotation sets.

Presentation

An ordered sequence of clips, pins, and title cards.

Video tutorials

Each workflow section below includes a short recording of the real app. The recordings are silent and captioned. Select a tutorial to jump to it.

01Your first projectCreate a project, import a match video, capture a possession with a modifier, open the clip editor, and add a pin.
02Capture and tag a passageTag a match while it plays, including overlapping clips and a modifier, then re-tag a clip and zoom the timeline.
03Draw and animate shapesDraw a box, move it to create keyframes, resize and rotate it, add a circle, and change the style of both at once.
04Trim a clipDrag both trim handles inward, check the summary, apply the trim, and undo it straight away.
05Track a playerChoose a player from the provisional highlights, start tracking, stop, and check the result at normal speed.
06Correct a trackA track jumps to the wrong player. Step back to the last good frame, re-track, step one frame when the tracker loses the player, and continue.
07Name players and attach an arrowName two tracked highlights, show their names on the video, and attach an arrow to both so it follows them.
08Annotate a pinAdd a pin, highlight two players, join them with an attached arrow, change its style, save, and close the pin.
09Animate a pinMake a pin’s annotations appear step by step, preview the sequence, then play into the pin from the clip.
10Draw on the pitchCompute the homography, check the pitch grid, draw a box on the pitch, and play through a camera pan.
11Build and present a deckCreate a presentation, add a clip, a pin, and a title, choose where the clip pauses, then present it.
12Export and recoverExport a report, find its files, delete a clip and undo the deletion, and back up the project folder.

First project workflow

The following procedure creates a project, imports a match video, captures one clip, and adds a pin to it. Drawing, tracking, presentations, and export are covered in later sections.

01
Create the project
Opening screen
Choose Create New Project, enter the match details you know, and select a parent folder.
Result: Annotate creates a normal project directory and opens its dashboard.
02
Import a video
Dashboard · Videos
Choose Import video and select the match file. Keep Annotate open while media is prepared.
Result: The video appears in the project with its own native frame rate and resolution.
03
Capture a clip
Capture player
Open the capture player, play the video, click a board tile at the first frame of the passage, add any modifiers, then click the same tile at the final frame.
Result: A tagged clip appears on the timeline and in the clip list.
04
Open the clip and add a pin
Clip editor
Select the clip and choose Open editor. Seek to the frame you want to explain and choose Add pin.
Result: The pin opens in its own window on that exact frame, ready for annotation.
05
Annotate, present, and export
Later sections
Draw on the clip or the pin, track players, build a presentation, and export a report when you need still images or clip data.
Result: Each of these has its own section and video below.

Your first projectVIDEO 01

Create a project, import a match video, capture a possession with a modifier, open the clip editor, and add a pin.

Install and run

Download the Mac DMG or Windows installer from GitHub Releases. On macOS, open the DMG and drag Annotate to Applications. On Windows, run the installer and open Annotate from its desktop shortcut. The packages target Apple Silicon with macOS 14 or newer, and Windows 10/11 x64.

These are unsigned evaluation builds, even when GitHub labels the release Latest. The operating system may ask for approval; do not disable its security protections. Python, video tools and models are bundled. No terminal or separate browser is needed. Services start and stop with the app; first launch can take longer while libraries initialize.

Desktop service logs are at ~/Library/Application Support/Annotate/logs/services.log on macOS and %APPDATA%\Annotate\logs\services.log on Windows. Clip and pin editors open in separate windows.

Browser development remains supported with Chrome, Edge, Brave, Arc or Chromium; Safari and Firefox cannot grant the required project-folder access. The archived browser installer and its instructions are in the repository’s legacy/browser-install folder.

Capture and tag clips

The tag board is a fixed working surface rather than a menu. Click a tile once to start a clip and click the same tile again to finish it. A recording tile shows a red dot and the frame it started from, and the clip in progress appears on the timeline before it is finished. Clips of different types may overlap.

Modifiers add structured details to the most recently started capture, so choose them while that capture is running. Their availability changes with the tile, but the board itself stays in place. There is no automatic pre-roll or post-roll: the frames you click become the clip boundaries.

Click a clip in the timeline or list to select it and seek to its start. While paused, choose Re-tag selected, then choose any modifiers and the new tile; the clip keeps its frames and moves to the new group in the list. You can also drag a clip onto another group. Open editor opens or focuses the clip in a separate desktop window.

The capture timeline uses separate group lanes and packs overlaps into subtracks. Click or drag to seek, scroll horizontally to move through time, and use the zoom slider to move between frame-level inspection and the whole match. Manual scrolling pauses automatic playhead following for five seconds.

The built-in board follows the language selected in the header. Custom boards keep their own labels. Changing language does not rename saved clips or cancel captures in progress.

Capture and tag a passageVIDEO 02

Tag a match while it plays, including overlapping clips and a modifier, then re-tag a clip and zoom the timeline.

Edit a clip

The clip editor combines the original video, animated tactical objects, a properties inspector, and a frame-native keyframe timeline. Playback never leaves the clip’s current in/out range.

Drawing an object creates its first position keyframe at the current frame. Step with the frame buttons or click the timeline to move to another frame, then move, resize, or rotate the object there: Annotate adds a keyframe and interpolates between them. Click a keyframe to return to its frame; edits there change that keyframe rather than adding a new one.

Color, line width, fill opacity, pattern, name, and other style properties belong to the object as a whole and apply on every frame. Use Select to click an object or drag an empty region for box selection. Shift-click adds objects in either the viewer or object list, and inspector changes then apply to all of them. Cmd-click on macOS or Ctrl-click on Windows subtracts objects. Merge is available for selected objects of the same type when their position keyframes do not overlap.

Draw and animate shapesVIDEO 03

Draw a box, move it to create keyframes, resize and rotate it, add a circle, and change the style of both at once.

Trim a clip

Choose Trim and drag either handle inward. The summary shows how many pins, keyframes, and objects the trim would remove. Apply trim commits the range and Cancel leaves it untouched. Undo trim restores the previous bounds until another clip edit is made. Trimming only shortens a clip; it cannot extend it past its original range.

Trim a clipVIDEO 04

Drag both trim handles inward, check the summary, apply the trim, and undo it straight away.

Keyframe rules

Position keyframes align to exact source-video frames.
Manual and correction keyframes can be dragged horizontally; tracked keyframes are fixed.
Delete removes selected keyframes. Shift+Delete removes selected objects.
An object must retain at least one position keyframe.
Tracking manages show/hide boundaries without changing position. There are no manual show/hide keyframe controls.

Track a player and correct mistakes

Seek to a clear frame and choose Track. Provisional highlights appear on the detected players.
Select the correct provisional player highlight, then choose Start. Choose Stop instead when only one manual frame is needed.
The video, highlight, and timeline follow tracked frames as they arrive. Preview updates may skip ahead if decoding falls behind, without discarding tracked keyframes. Pins do not interrupt tracking.
Choose Stop when you have enough. The playhead returns to where tracking started so you can play the result back.

Track a playerVIDEO 05

Choose a player from the provisional highlights, start tracking, stop, and check the result at normal speed.

Correct a track

When continuity is lost, the tracked highlight hides and provisional candidates return. Select the matching candidate and choose Continue; Annotate fills the gap and resumes. If the right player is not detected on that frame, step forward one frame at a time until they are, then continue. Sometimes you need to do this several times.

If the track has followed the wrong player, play back to the switch, step back to the last frame where it was correct, and choose Re-track from here. Select the right player and continue. Done replaces the old tail of the track; Cancel keeps the original.

Tracking uses image coordinates and does not require a homography. Tracker IDs are continuity hints, not permanent player identity, so expect to correct tracks around overlaps, camera cuts, and players leaving the frame.

Correct a trackVIDEO 06

A track jumps to the wrong player. Step back to the last good frame, re-track, step one frame when the tracker loses the player, and continue.

Name players and attach shapes

Select a highlight and type the player’s name in Name. Tick Display name to show it on the video, and adjust Text size as needed. The name also labels the object in the timeline.

Arrow, Lob, Shadow, and Poly can attach to highlights. With Arrow selected, click one highlight and then another: both ends attach, so the arrow follows the players through tracked motion without being redrawn.

Pins and animations

A pin marks one exact frame inside a clip. Choose Add pin in the clip editor to open the pin in its own window on that frame. The pin editor uses the same drawing tools as the clip editor, and an arrow drawn from one highlight to another stays attached to both. Choose Save, then Close pin to return to the clip.

Hold Left or Right to look at up to five seconds of surrounding video; annotations hide and editing locks away from the pin frame. Space returns to the exact editable frame. A pin can also hold several named annotation sets when the same moment needs alternative explanations, and Import into clip copies the active set into the clip at the pin frame.

Annotate a pinVIDEO 08

Add a pin, highlight two players, join them with an attached arrow, change its style, save, and close the pin.

Animate a pin

Open Animations in the pin editor, select a shape, and choose Add. Each step has an effect (Appear, Fade, Grow, or Wipe) and a trigger: On click, With previous, or After previous, with an editable delay and duration. The default is Fade, On click. Shapes without a step are shown from the start. Preview and Next step through the sequence.

When a clip plays into a pin with animations, playback stops at the pin with the animated shapes hidden. Play, Space, or a click on the video runs each click step in turn, and the next click after the last step resumes the clip.

Animate a pinVIDEO 09

Make a pin’s annotations appear step by step, preview the sequence, then play into the pin from the clip.

Draw on the pitch

To draw on the pitch itself, the clip needs a homography. Choose Compute H. The progress bar shows model loading and then the sample frames being calibrated across the clip; the first computation after starting the app takes longer. Cancel stops without replacing an existing result. Results are cached, and Recompute H replaces them.

Show H overlays the pitch grid so you can check it against the markings. When a homography is available, Box and Circle draw on the pitch (Draw: pitch): they take the pitch’s perspective, their handles move on the pitch, and they stay on the same area of grass as the camera moves. Shapes drawn in image coordinates stay fixed on screen instead.

Delete H removes the homography and returns drawing to image coordinates. Pin calibration offers the same automatic solver plus a Manual H fallback for one frame. Tracking does not need a homography.

Draw on the pitchVIDEO 10

Compute the homography, check the pitch grid, draw a box on the pitch, and play through a camera pan.

Create and play a presentation

Create a presentation from the dashboard: type a name, choose Create, then Open. The authoring workspace contains an asset browser, live preview, horizontal slide deck, and inspector.

Click an asset to preview it; nothing is added until you drag it into the deck. Expand a clip’s pins to drag one in as its own slide. Use Add title for title, section, or divider cards, and drag slide thumbnails to reorder them. Select a clip slide to choose which of its pins it pauses at.

Present removes the editor UI and fills the viewport. Clip slides play the original video with their animated annotations and pause at the chosen pins; clicks reveal pin animation steps before the clip resumes or the presentation advances. Cut changes directly to the next slide, and Match video is available between forward-ordered pins from the same video.

Build and present a deckVIDEO 11

Create a presentation, add a clip, a pin, and a title, choose where the clip pauses, then present it.

Export, recover, and inspect

Export report… on the dashboard writes clips.csv, clips.json, and one PNG at the video’s resolution for every pin annotation set, inside the project folder at exports/report/. PNGs show the completed annotation rather than one instant of an animation.

To remove a clip, select it in the capture player and choose Delete clip. Deleting clips, pins, and annotation sets first copies them into .trash/; use Undo delete straight away to restore one. Empty trash permanently removes retained recovery data.

To remove a video, use Delete beside it on the dashboard and confirm Delete video and clips. This permanently removes the project video copy and all its clips, pins, and annotation sets. The original input file and presentation decks are unchanged; affected slides report missing sources. Video deletion has no Undo.

The dashboard integrity report lists missing media, unreadable documents, and unresolved presentation references. It is diagnostic: Annotate does not guess how to rewrite authored work. To keep everything safe, back up the whole project folder.

Export and recoverVIDEO 12

Export a report, find its files, delete a clip and undo the deletion, and back up the project folder.

Workspace map

Workspace	Purpose	Primary output
Dashboard	Create/open projects, import video, edit match metadata, manage presentations, export, and inspect integrity.	Project configuration and reports
Capture player	Watch a full video and tag overlapping passages with the fixed board.	Clips
Clip editor	Animate tactical objects, track players, compute homography, trim inward, and add pins.	Clip annotations and pins
Pin editor	Create one or more annotation sets and entrance-animation sequences on an exact frame.	Annotation documents
Presentation editor	Arrange clips, pins, and title cards into an authored sequence.	Presentation
Present mode	Play the sequence without authoring controls.	Full-screen playback
Match details	Maintain teams, players, coaches, score, competition, venue, and other match metadata.	Project metadata

Drawing tools and coordinates

Tool	Coordinates	Behavior
Select	Image or pitch	Select, move, resize, rotate, or box-select objects. Shift-click adds to a selection.
Box	Image or pitch	A rectangular area. In Draw: pitch it stays fixed to the pitch plane as the camera moves.
Circle	Image or pitch	An elliptical area with resize and rotation handles. Pitch mode behaves like Box.
Highlight	Image	A player marker. It can be named, tracked, and used as an anchor for linked shapes.
Shadow	Image	A defensive cover shadow with direct radius, direction, and spread handles.
Arrow	Image	A directional action. Either endpoint can attach to a highlight.
Lob	Image	A curved pass path with the same highlight-linking behavior as Arrow.
Poly	Image	A closed area or open line. Vertices can attach independently to highlights.
Text	Image	Static explanatory text. Style belongs to the object rather than individual keyframes.

Arrow, Lob, Shadow, and individual Poly vertices can attach to highlights. Attached geometry follows its highlight through manual or tracked motion. Only Box and Circle use pitch coordinates; all other tools remain in image coordinates.

Keyboard shortcuts

Context	Shortcut	Action
Capture	Board hotkey	Toggle the assigned clip range or modifier.
Capture	Escape	Cancel re-tagging or the most recently started active range.
Capture	Delete / Backspace	Move the selected clip to project trash.
Clip editor	Space	Play, pause, trigger a pin animation, or resume from a pin.
Clip editor	Left / Right	Step exactly one source-video frame.
Clip editor	K	Add or replace a position keyframe at the current frame.
Clip editor	Delete / Backspace	Delete the selected keyframe.
Clip editor	Shift + Delete / Backspace	Delete the selected object.
Clip editor	Cmd/Ctrl + Z	Undo the last editor change.
Clip editor	Cmd/Ctrl + Shift + Z	Redo the last editor change. Ctrl + Y also works.
Clip or pin editor	Enter	Finish a closed polygon.
Clip or pin editor	Shift + Enter	Finish an open polygon line.
Pin editor	Hold Left / Right	Preview up to five seconds around the pin.
Pin editor	Space	Return to the exact editable pin frame.
Present mode	Left / Right	Move backward, trigger the next animation, or advance.
Present mode	Space / click	Trigger the next animation or resume a paused clip.
Present mode	Escape	Exit full-screen presentation playback.

Shortcuts are ignored while focus is inside a text input, text area, or select control.

Glossary

Annotation set: One independently saved frozen-frame explanation attached to a pin. A pin may contain several alternative sets.
Board: The fixed spatial arrangement of capture buttons and modifiers used to tag passages during video review.
Clip: A frame-bounded passage of play. Clips may overlap and remain independent even when they use the same source video.
Coordinate mode: The space in which object geometry is stored: image pixels or pitch coordinates projected through homography.
Facet / modifier: Additional structured information attached to a clip, such as outcome or phase detail.
Homography: A frame-by-frame mapping between the visible image and the football pitch plane.
Keyframe: An exact source-video frame where an animated object stores geometry. Tracking also records automatic stop/loss markers; there are no manual show/hide keyframe controls.
Object: A shape in the animated clip layer, such as a highlight, arrow, polygon, or text label.
Pin: An important exact frame inside a clip. Pins own frozen-frame annotation sets and can pause clip playback.
Presentation: An ordered sequence of clips, pins, and title cards with playback and transition settings.
Source frame: The absolute frame number in an imported video. Annotate uses frames rather than approximate timestamps for authored timing.
Tag: The primary board classification that describes what a captured clip represents.
Tracking: Automatic player following that creates highlight position keyframes. Human reacquisition corrects losses or identity changes.
Visibility keyframe: A tracker-managed show or hide boundary for an animated clip object. It does not store position; there are no manual show/hide controls.

Project files and backups

A project is an ordinary directory. Its manifest is project.json; source media lives under media/; clips and their annotation documents live under analysis/; presentations, exports, caches, and trash use their corresponding folders.

Do not rename or move internal files while a project is open. To back up or move a project, close it and copy the complete folder. Videos are copied into the project, so storage must accommodate both the source file and project copy during import.

Annotate 0.2 projects use the project.v2 model and are not compatible with Annotate 0.1. Keep a pinned 0.1 installation for older projects.

Troubleshooting

A project folder will not open

Confirm the folder is writable and contains project.json. Browser users also need Chromium folder permissions; Safari and Firefox do not provide the required folder API.

The sidecar is offline

Quit and reopen Annotate. Retain the startup error and service log; see Install and run for log locations. The desktop app chooses its own local service ports.

A pin opens nowhere

In the desktop app, check for an existing pin window; reopening the same pin focuses it. In a browser, allow pop-ups for the app address and try again.

The first tracking run cannot load

Desktop packages bundle the YOLO model. Restart and report the error with the service log. Browser development may download the model on first use.

Homography is unavailable

Desktop packages bundle PnLCalib and its model weights. Restart Annotate and report the startup error and service log if it persists.

Video import is slow

Compatible constant-frame-rate H.264 MP4 is preserved or remuxed. Other codecs and variable-frame-rate media require a full transcode. Canceling safely removes temporary import files.

Tracking changes player during an overlap

Stop at the last trusted frame, choose Re-track from here, select the correct provisional player, and continue. Cancel leaves the original tail intact.

The integrity report lists a missing item

Restore it from .trash when possible, or remove the broken presentation reference. Annotate reports the path rather than silently rewriting authored work.