Importing Videos

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

Three Ways to Import

Every lecture in Harvestry starts with an import. There are three 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/.
Safari extension — While browsing a video page in Safari, click the Harvestry toolbar button to send the URL directly to the app with one tap. No copy-pasting required.

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.

Some videos require you to be signed in to download them — corporate learning platforms, university course portals, and similar sites. Harvestry can pass your browser's saved session cookies to yt-dlp so it can authenticate on your behalf.

Enabling cookie import

Open the Import sheet and switch to the URL tab

Click + or use File → Import Video, then click the URL tab.

Check "Requires sign-in"

Tick the Requires sign-in checkbox beneath the URL field. A browser picker appears.

Choose your browser

Select the browser where you are already logged in to that site — Safari, Chrome, Firefox, Brave, or Edge. Harvestry passes the --cookies-from-browser flag to yt-dlp, which reads the browser's local cookie store without opening the browser.

Click "Download & Import"

The download proceeds as normal. If authentication succeeds, the video downloads and the lecture appears in the sidebar.

ℹ️

If the download fails with a login error, Harvestry shows a dialog explaining that the site requires sign-in and offers to retry with cookie import enabled. You can pick a browser and retry without starting over.

⚠️

Your cookies never leave your Mac. The browser cookie store is read locally by yt-dlp and used only to authenticate the download request. Harvestry does not transmit your cookies to any server.

Importing with the Safari Extension

The Harvestry Safari extension lets you send a video URL to the app directly from your browser — no copying, no switching apps to paste. It works on YouTube, Vimeo, and most other supported video platforms.

Installing the Extension

Open Safari Extensions preferences

In Safari, go to Safari → Settings → Extensions (or press ⌘, then click the Extensions tab).

Enable Harvestry

Find Harvestry in the extensions list and tick the checkbox to enable it. The Harvestry toolbar icon will appear in your Safari toolbar.

Grant permission when prompted

The first time you use the extension, Safari may ask whether to allow Harvestry to read the current page. Allow it — the extension only reads the page URL and title to populate the import sheet.

Using the Extension

Navigate to a video page

Open any video page in Safari — a YouTube lecture, a Vimeo talk, a course video, or any other supported site.

Click the Harvestry toolbar button

The extension popup appears, showing the video title if the page is recognised, or a generic "Try importing this page" prompt for less common sites. Click Import into Harvestry.

Harvestry opens with the URL pre-filled

The app comes to the foreground and the Import sheet opens with the URL already populated in the URL tab. Review it and click Import to start the download and processing pipeline.

ℹ️

Harvestry must be running. The Safari extension opens a harvestry:// URL to communicate with the app. If Harvestry is not already open, macOS will launch it automatically before opening the import sheet.

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.

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.

💡

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