Install ReelForge
The native downloads include Python, FFmpeg, ffprobe, and Deno. No command-line setup or separate media-tool installation is needed.
macOS
- Download the Apple Silicon DMG or Intel Mac DMG.
- Quit any existing ReelForge instance. Open the DMG and drag ReelForge into Applications.
- Open the newly installed app from Applications. Pin its icon to the Dock if desired.
- If macOS blocks first launch, follow Apple’s Privacy & Security → Open Anyway instructions for a download you trust. Keep Gatekeeper enabled.
This free release uses no paid Apple signing or notarization. The queue and saved date reviews are stored separately under ~/.reelforge. Run one instance at a time.
Windows
- Download and run ReelForge Setup.exe.
- Follow the installer. Microsoft WebView2 may need an internet connection during setup.
- Open ReelForge from the Start menu or its optional Desktop shortcut.
The Apple Silicon Mac version has been installed and tested by the project owner. Intel Mac and Windows passed automated checks and await hands-on installation testing. See release notes and checksums.
Source and development
Developers can use the GitHub source and build instructions. The source setup launchers require separately installed Python and media tools.
Your first collection
- Import a sourcePaste a supported URL under Playlist / video and click Scan. Website, JSON index, and Manifest cover other source formats. Scanning lists videos; it does not download media.
- Review and selectCheck titles and use Edit to correct metadata. New scans select all entries. Use Clear, then tick the videos you want. Filters hide rows without clearing hidden selections.
- Choose a destinationUnder Make it yours, browse to a folder on your computer or an already mounted network share. Set a collection name.
- Preview filenamesChoose a naming preset, source quality, and MKV or MP4. Review the path beneath each video. Resolve metadata errors or duplicate output paths before queueing.
- Queue the selectionClick Queue selected. Leave Join selected videos off to save separate files, or turn it on to create one combined file.
- Follow the queueIn browser mode, keep the launcher terminal open. In desktop mode, keep the app window open. Download queue shows progress and Pause, Resume, Retry, or Cancel as appropriate. Completed files appear in the destination you chose.
Explore without a download: Try a sample previews the interface using fictional metadata. Sample mode deliberately disables downloads. Import real source URLs to queue media.
Understand dates and filters
Finding a video and identifying its original date are separate steps. A year in an uploader’s title is a claim. An upload timestamp does not establish when the footage originally aired, was released, or was recorded.
- Import your videos, then click Research dates for a fast title/reference pass. Entering a year range alone does not research anything.
- For more evidence, enable Fetch descriptions online and research again. You can import your own reference JSON under Reference library. No subject catalogue is loaded automatically.
- Enter From year and Through year, then choose Documented only or Documented + likely.
- Click a confidence count or use View all likely dates to inspect every likely result. Outside and overlapping views explain exclusions. Other title/duration filters still apply.
- Click Select matches only to replace your download selection with qualifying videos. Open a video’s Dates panel to inspect sources or save your own decision.
Confidence describes the evidence available, not a statistical probability.| Status | What it means |
|---|
| Documented | A matching imported reference or a documented manual review. The exact uploaded edit has not been automatically verified. |
| Likely | A date claim from a title, an explicit original-date statement in a description, or a reference page you supplied. |
| Unknown | There is not enough usable evidence, or a reviewer left the date unresolved. It does not mean outside the period. |
| Conflicting | Date claims disagree. The video is excluded from automatic date selection until reviewed. |
Why can 3 likely become 2 matches? Suppose three likely dates are 1999, 2001, and 2005. All three count as likely, but only two fit 2000–2009. The whole suggested range must fit, and the confidence setting must allow it.
Selection matters: Research dates clears the download selection. Changing a view does not select or deselect videos. Select matches only replaces the selection across the entire collection, even when a title filter hides some matches.
Name, organize, and join
| Preset | Use it for |
|---|
| Numbered playlist | A collection folder with an index and title: Collection/001 - Video title.mkv. |
| TV episodes | Season folders and episode labels. Enter a show name and supply missing season/episode metadata with Edit. |
| Source filenames / folders | Names and subfolders supplied by your index or manifest. Without those fields, the video title becomes the filename directly in the destination. |
| Custom template | Control the path using fields such as {collection}/{index:03d} - {title}. Leave out the file extension. |
MKV preserves source codecs when merging video and audio. MP4 converts to H.264/AAC for broad playback compatibility. A resolution preference limits known source resolutions; it does not upscale low-resolution footage.
Join selected videos combines entries in collection order, not the order you click checkboxes. TV episode collections follow recognized season/episode order. Normalize join converts parts to a common 720p/30 fps H.264/stereo AAC format; Fast join requires compatible streams. Conversion can take time.
Frequently asked questions
Is ReelForge free? Does anyone need an API key or subscription?
This release is free to download and run. It has no paid API integration, subscription, or account requirement. Python, yt-dlp, FFmpeg, and the other required software can be obtained without a software fee. You supply your computer, internet connection, and storage. ReelForge’s source is distributed under the MIT license; dependencies retain their own licenses.
Why are there more likely videos than matching or visible videos?
Confidence counts cover the entire imported collection. Matches also need to fit completely inside your year range and meet the confidence setting. Visible rows additionally respect title, exclusion, and minimum-duration filters. Click the likely count to see all likely dates; check outside and overlapping views for excluded dates. Clear other filters if needed.
Why are all dates unknown, or the results empty?
A scan imports entries; it does not run date research. Click Research dates first. A view restricted to matches can hide all unknown entries. Switch to View all dates / statuses, then check the research status message. Unknown results can remain after research when usable evidence is missing.
Does Research dates search the web or watch each video?
This release checks titles, optional fetched descriptions, references you import, and reviews you save. It does not autonomously search the web, watch footage, perform OCR, or transcribe speech. The Dates panel can open a web search and read a reference page URL you supply. It cannot guarantee a historical date for every video.
Can I use a different playlist, topic, or website?
Yes. No show, team, channel, or decade is built into the workflow. Supported video URLs use yt-dlp. Website scans read static links and embeds; sites that depend on JavaScript may need a directly supported video URL, JSON index, or manifest.
Why is Queue selected disabled?
Check that at least one video is selected and the filename preview has finished. Scanning, research, metadata errors, and output-path collisions can prevent queueing. Sample mode also disables downloads until you import real source URLs.
Why are hidden videos still selected?
Filters change what you see, not the saved download selection. Clear removes the selection across the collection. Select visible changes the visible rows. Select matches only replaces the selection using date rules across the whole collection. Check the selected count before queueing.
Does the app download both video and audio?
For supported sources, yt-dlp retrieves the available streams and FFmpeg merges separate video and audio when needed. The app checks the resulting media before delivery. Audio cannot be recovered if the source does not provide it.
Can it save directly to my NAS, Plex, ErsatzTV, or Fieldstation42 folders?
Choose an already mounted share or local folder as the destination and preview the path. The app writes files; it does not configure a NAS, mount shares, refresh Plex, or manage ErsatzTV or Fieldstation42. Your operating system must have write access to the destination.
Will it replace existing files or remove duplicates?
Existing final paths are kept and skipped. Conflicting planned filenames are flagged before queueing. This is not content-based duplicate detection: the same video under another filename is not automatically recognized.
What survives closing or updating the app?
The download queue, saved date research, reviews, and imported reference library live in the home-folder database. Interrupted jobs reopen paused. The current imported list and unsaved selection are not a saved project; export a manifest before leaving if you want to reload it. Unchanged source URLs and titles restore saved date reviews when rescanned.
How do I update and confirm I opened the right version?
Quit ReelForge. On Mac, open the new DMG and replace the app in Applications; on Windows, run the new installer. Open the newly installed copy and check the version at the bottom of its sidebar, or in Setup & about on a narrow screen. Keep the home-folder database to retain saved jobs and reviews. Source users should follow the GitHub source setup instructions instead.
When something gets stuck
macOS blocks first launch
Follow Apple’s Open Anyway instructions for a download you trust. Keep Gatekeeper enabled. No Terminal command is needed for this exception.
The browser cannot connect, or says Session expired
The browser needs the local Python process to be running. Reopen the app with its launcher and use the browser tab it opens. An old bookmarked address may point to a previous port or session.
FFmpeg setup needed, missing audio, or a join fails
Open Setup & about to check engine health. Native downloads include the media tools; reinstall the current release if a bundled tool is missing. For incompatible join inputs, try Normalize join and inspect the job’s Error details if it still fails.
A video download fails or is unavailable
Open Error details in Download queue. Check that the source is still available and supported, and that the destination is writable with enough free space. Retry after resolving the cause. Check the GitHub releases for an updated app if a supported source stops working. DRM, access restrictions, and unsupported sites are not handled by this release.
Nothing is shown, but the collection count is nonzero
Switch to View all dates / statuses and clear the title, exclude, and minimum-duration filters. These filters can hide entries while the collection and selection counts remain unchanged. A minimum-duration filter also hides videos whose duration is unknown.
Research is slow or descriptions fail
Description lookups run one at a time and can time out. Try a smaller batch with Selected videos only. Cancel research keeps completed results. When a lookup fails, available title/reference evidence remains; check the research warning and each video’s Dates panel.
Why ReelForge exists
Preparing a local media collection often means repeating the same work: finding videos, pairing video and audio, cleaning filenames, organizing folders, and recovering interrupted downloads. ReelForge brings those steps into one reusable workflow with a preview before downloading.
Created by Zakery Holzapfel, the project grew from scripts used to prepare local media collections, including a Fieldstation42 setup. Its folder-based workflow can prepare media for Plex, ErsatzTV, and Fieldstation42. It now supports general collections, recordings, episodes, and archives through configurable sources and naming rules.
ReelForge is a free tool people can run on their own computer and adapt to their libraries. Download the bundled desktop app for its own window, or use the source for local browser mode and development.
Built with
ReelForge provides the interface, source mapping, naming preview, persistent queue, date review, and delivery workflow. Existing open-source projects provide the underlying extraction and media processing.
ReelForge is MIT licensed. Dependencies retain their own licenses. Plex, ErsatzTV, and Fieldstation42 are separate projects. Use media you are authorized to download.
