PVA Photo and Video Annotator

PVA, the Photo and Video Annotator, is a desktop application for organizing and viewing images and videos in a folder, making it easy to click through media files, add detailed annotations to images and videos, skip unwanted segments of videos, and view the results as a slideshow.

Walkthrough video

Features

Preparation of Files

File and folder organization

Put the images and videos you want into a single folder. Your folder of images and videos can have subfolders with additional images and videos.

When you launch PVA, select the folder containing your photos and videos. You’ll be prompted to confirm which subfolders to include in your annotation project. The program will read any existing annotations from an annotations.json file in the main folder, or create one if it doesn’t exist.

You can add additional files to the folder or subfolder any time you like; PVA will detect them the next time it starts. You can manually remove files from the folder, PVA will not complain that they are gone. But if you rename a file, PVA will not associate the new name with information stored for the old name. PVA reduces the need to edit image files directly.

Supported Formats

Images: JPG, JPEG, PNG, GIF, BMP, TIFF, TIF, WebP

Videos: MP4, MOV, AVI, MKV, FLV, WMV, WebM, M4V, 3GP

Navigation buttons

Sort Order

Files are sorted by creation date, which is determined intelligently:

Buttons and Keyboard

Skip or Discard File

Click the Skip button to hide a media file from view. The file is marked as skipped in the annotations and will be automatically passed over when navigating forward or backward.

Click the Discard button to move a file to a discard subfolder. This is like deleting a file, but not as severe.

Slideshow

Click the Slideshow button to automatically cycle through your media files:

Image annotation and display modifications

Image Annotations

For images, you can add and edit a text description:

  1. Click in the text box at the bottom of the screen
  2. Type your annotation (e.g., “Family picnic in the park” or technical details about the photo)
  3. Click elsewhere indicate that you are done editing

The text is automatically saved to the JSON file under the text field for that image.

Rotate Image

Click the Rotate button (only available for images) to rotate a photo clockwise:

The rotation preference is saved for the image in the JSON file and will be remembered the next time you view it.

Location Information

The application automatically extracts GPS coordinates from photo metadata using EXIF data. When coordinates are found, it performs a reverse geocoding lookup using OpenStreetMap’s Nominatim service to determine the city, state, and country.

Automatic Location Detection

When you view a photo with GPS data:

  1. The application extracts latitude and longitude from the photo’s EXIF metadata
  2. It automatically looks up the address
  3. The location is stored as location.automated_text in the JSON file
  4. The location appears in the location dropdown

Manual Location Entry

You can also manually set or override the location:

  1. Click on the location dropdown on the right side of the screen
  2. Either type a new location or select a previously used location from the list
  3. The location is saved as location.manual_text in the JSON file
  4. If both manual and automated locations exist, the manual location is displayed

The dropdown shows all unique locations (both manual and automated) across all files in your collection, making it easy to maintain consistency.

Video Display and Annotations

Video display and annotation

Playing Videos

When you navigate to a video:

  1. The video begins playing automatically
  2. The volume is set to whatever you previously selected (or 100% if newly displayed)
  3. Use Play/Pause to control playback
  4. Use Replay to restart from the beginning
  5. Click on the progress slider to jump to a specific time, or hover over it to see timestamps

Video Volume Control

For videos, use the Volume button (showing the current volume level) to adjust playback volume:

Use this to mute videos with too much background noise or to reduce or equalize volume for quieter content.

Add Video Annotation

Videos support more sophisticated annotation: you can add multiple text annotations at different time points, and mark segments to be automatically skipped.

To add a text annotation at a specific time:

  1. Pause the video at the desired time point
  2. Click Add annotation
  3. Type your text (e.g., “Golden retriever enters the scene”)
  4. Click elsewhere or press tab to save
  5. The annotation is saved with the current video timestamp

You can add as many annotations as you want throughout the video, each with its own timestamp.

Edit Video Annotation

To edit an existing annotation:

  1. Pause the video at any time within an annotated segment (the annotation text will appear in the text box)
  2. Click Edit annotation
  3. Modify the text
  4. Click elsewhere to save

The text is updated while the timestamp remains unchanged.

Skipping Video Segment

To mark a segment of the video to be automatically skipped during playback:

  1. Pause the video at the point where you want skipping to begin
  2. Click Skip until next annotation
  3. The video marks this point and jumps to the next annotation (or end of video)
  4. During playback, when this skip point is reached, the video automatically jumps to the next annotation
  5. There is no particular limit to the number of segments that can be skipped

This is useful for removing unwanted sections (background noise, false starts, etc.) without deleting the original video file. You can adjust the slider into a skipped segment to remove the skip annotation, if desired, or to start a new annotation where the video should start playing again.

Removing Video Annotation

To delete an annotation:

  1. Pause the video during the time of the annotation you want to remove
  2. Click Remove annotation
  3. The annotation is deleted and the video returns to the previous annotation

Download and Install Executable Files

The easiest way to use PVA is to use the download link below to get the file(s) necessary for your operating system.

Go to the latest release

Windows

Download:

Notes:

macOS

Download both:

On the first run:

  1. Save both files in the same folder
  2. Double-click run_PVA_macOS.command to set permissions
  3. The script will prepare and launch the app

After that, you can launch PVA_Photo_and_Video_Annotator_macOS directly

Linux

Download:

Make executable if needed:

chmod +x PVA_Photo_and_Video_Annotator_Linux

Technical Details

Storage and Formats

All annotations, metadata, and preferences are stored in a JSON file (annotations.json) in your media folder. The JSON format makes it easy to:

However, be careful with JSON format because the brackets and commas are very important; it is better to avoid editing the JSON file if at all possible.

Date and Time Handling

The application intelligently determines creation dates for your media files:

The goal is that files are always sorted in the order they were taken, regardless of whether they were downloaded, emailed, or copied to your collection.

JSON File Entries

The file annotations.json stores the text you type and the location information that PVA extracts and looks up online.

Each media file gets an entry in the JSON with:

The application also stores settings in the _settings object: