egaia roughcut

This tool generates a rough-cut video out of a list of clips, represented in a format generated by egaia derive.

Usage

egaia roughcut --help
egaia roughcut [ --video ] [ --finding-aid ] [ --title=TITLE ] LIST

Options

--help

Display this help text and exit.

--video

Generate a video out of clips referenced in the edit list LIST. This command takes as its input a CSV file listing clips from the archive, along with their in-points and out-points, and optionally titles and captions. The tool will extract working copies of the clips referenced in this file to a clips.dir directory in the current collection, normalized to 1080p @23.97fps, h264 codec. Existing clips in this directory are ignored. The clips provided in the input list are then assembled using an ffconcat edit list.

--finding-aid

Generate a finding aid based on the text extracted from the “caption” field for each edit. If there is caption text associated with a given edit, extract a thumbnail image from the middle of the target clip and print the thumbnail, time, and caption to a docx file (BASENAME.df-video-description.UUID.docx). Text from “title” fields will be included as unstyled paragraphs, without thumbnails. If a video title is specified using the --title flag, that will be used as the title for the document (which will otherwise be empty).

--title=TITLE

Use TITLE as the title for the rendered video, as provided in the video metadata and in the finding aid.

LIST

A CSV-format edit list, containing at minimum input clips with in-point and out-point timings. See below for the format of this file.

Usage notes

This tool provides imprecise but quick editing workflow that accommodates the rapid production of videos out of a large fonds of observational film or similar sources, for research or public presentation. Re-rendering the project after editing the input list should always be quick, as the pre-rendered clips are simply concatenated each time.

The h264 derivative file for each source clip in the public directory (defined as pub_path in the configuration file) will be used as a basis for the edit, but if the original clips are available a final edit can also be prepared by modifying the input paths in the ffconcat edit list prepared by this tool. (Egaia does not currently provide an automated means of doing this, as the locations of source clips in a distributed archive can be difficult to determine.)

Each line in the input file normally represents one title or video clip in the target video. The CSV fields that are currently parsed by this tool are listed below; they should be identified by a header row, but do not need to be in a specific order.

reel

The UUID of the source clip (or source directory, if it is a directory of raw footage).

clip

The clip filename (e.g., MOV00742_01.MP4).

inpoint

The in-point, in seconds (e.g., 3 or 7.422). This should be relative to the beginning of the source clip, not the reel.

outpoint

The out-point, also in seconds

title (optional)

Text that will be shown on-screen as a title clip (intertitle).

caption (optional)

Descriptive text that will be printed in a finding aid for the rendered video.

This tool is intended to be used in conjunction with the still images created from video files by egaia derive. Using the html contact sheet for these videos, you can click on an image to have a line of text copied to the clipboard containing the information for egaia roughcut to include a 6-second clip centred on that image. Paste this text manually into a text file or spreadsheet saved in CSV format, and adjust the in-point and out-point as desired.

Known limitations

If any of the source clips is missing an audio track, the resulting video will be created without audio. (The title clips generated by this tool do contain a silent audio track to counteract this limitation.)