Importing Videos

Harvestry accepts local video files and URLs from YouTube, Vimeo, and over a thousand other video platforms.

Two Ways to Import

Every lecture in Harvestry starts with an import. There are two methods:

Local file — Pick a video already on your Mac. No internet required. The file stays in its original location; Harvestry stores only the path.
URL — Paste a YouTube, Vimeo, or other video URL. Harvestry downloads the video using yt-dlp (installed automatically) and saves it to ~/Library/Application Support/io.archetyp.Harvestry/downloads/.

Importing a Local File

Open the Import sheet

Click the + button at the top of the library sidebar, or use File → Import Video from the menu bar.

Select the Video File tab

The Import sheet opens to the Video File tab by default.

Choose your file

Click Choose File to open the system file picker. Supported formats are .mp4, .mov, and .m4v. Select your file and click Open.

ℹ️

Don't move the original file. Harvestry stores the absolute path to your video. If you move or rename the file after import, the lecture will show a Missing status and playback will stop working. You can re-import the file at its new location if this happens.

Supported Formats

The file import picker accepts the following extensions:

.mp4 — MPEG-4 video. H.264, HEVC (H.265), and AV1 codecs are supported (AV1 is transcoded automatically).
.mov — QuickTime Movie. H.264 and HEVC containers are fully supported.
.m4v — iTunes video format, essentially a DRM-free MPEG-4 container.

Importing from a URL

URL import supports YouTube, Vimeo, and over a thousand other sites via yt-dlp. Both yt-dlp and ffmpeg are installed automatically on first use — you do not need to install them via Homebrew or any other method.

Open the Import sheet

Click the + button or use File → Import Video.

Switch to the URL tab

Click the URL tab in the Import sheet.

Paste the URL

Paste the full video URL into the text field. Examples: https://www.youtube.com/watch?v=…, https://vimeo.com/….

Click "Download & Import"

Harvestry starts downloading the video. A progress bar appears in the Import sheet. Depending on video length and your connection speed, this may take from a few seconds to several minutes. The sheet dismisses automatically when the download completes and the lecture appears in the sidebar.

⚠️

Respect copyright and terms of service. Only download videos you have the right to download. Many platforms prohibit downloading in their terms of service. Harvestry is designed for use with content you own or that is licensed for offline study.

Video Quality and Format

Harvestry instructs yt-dlp to prefer H.264 (AVC) video over VP9 or AV1. This is because AVAssetImageGenerator — the macOS API used for screenshot capture — cannot perform reliable random-access seeks on VP9 or AV1 content. If a site only offers VP9 or AV1, Harvestry automatically transcodes the downloaded file to H.264 before processing. You will see a "Converting video format…" progress indicator when this happens.

What Happens After Import

Immediately after import — whether from a file or a URL — the following has happened:

A new lecture entry appears in the library sidebar with a Ready status badge.
The lecture's title is set from the video filename or the downloaded video's metadata title.
No transcription or screenshot work has started. Processing is manual — you trigger it by clicking Begin Processing on the lecture detail view.
For URL lectures, the original source URL is stored so Harvestry can detect duplicates and offer a re-download option if needed.

Duplicate Detection

Harvestry checks for duplicates at two points during import:

Before download (URL import)

If you paste a URL that matches a lecture already in your library, Harvestry shows a confirmation dialog before starting the download. Options:

Open Existing — Dismiss the sheet and select the existing lecture in the sidebar.
Re-download & Reprocess — Delete the old file, download fresh, and re-run the pipeline from scratch. Useful if the video was updated or the previous download was corrupted.
Cancel — Do nothing.

After download (file path match)

If the downloaded or selected file path matches a lecture already in the library, the same dialog appears. Options are identical, but "Re-download" becomes Reprocess from Scratch since the file already exists.

Re-downloading a URL Lecture

If you previously imported a lecture via URL and want to download it again (for example, after the source was updated, or if the original download was a lower-quality version), you can re-download without deleting the lecture:

Select the lecture in the sidebar.
In the detail view, click the ⋯ menu or right-click the lecture row in the sidebar.
Choose Redownload (this option only appears if the lecture has a stored source URL).

Harvestry passes --force-overwrites to yt-dlp, which discards any cached stream shards from the previous download and fetches a fresh copy. The lecture is then re-processed from the beginning.

💡

Keep yt-dlp up to date. Video platforms frequently change their streaming APIs. If a URL download fails, go to Settings → Video Downloader and click Check for Updates to update yt-dlp to the latest version.

Previous Getting Started

Next The Processing Pipeline