Fireshare continuously scans your mountedDocumentation Index
Fetch the complete documentation index at: https://mintlify.com/ShaneIsrael/fireshare/llms.txt
Use this file to discover all available pages before exploring further.
/videos directory and turns every supported video file it finds into an entry in a browsable, searchable library. No manual imports are required — drop a file into the folder and it appears in the dashboard on the next scan cycle. The library is the heart of the application, and everything from thumbnails to view counts to privacy flags flows from how videos are organized on disk.
How Library Scanning Works
Fireshare runs a background scan on a fixed interval controlled by theMINUTES_BETWEEN_VIDEO_SCANS environment variable (default: 5 minutes). Each scan cycle walks the /videos directory tree, registers any new files it has not seen before, and marks any previously known files that have been deleted as unavailable.
Set
MINUTES_BETWEEN_VIDEO_SCANS to a lower value if you upload files frequently and want near-instant library updates. See Environment Variables for the full list of tunables.Directory Structure and Folders
Each immediate subdirectory of/videos becomes a folder in Fireshare’s UI. Files placed directly in the root of /videos are scanned but not grouped into a named folder. Files nested deeper than one level are still discovered but are attributed to their top-level parent subdirectory.
Supported File Types
Fireshare recognizes the following container formats:| Extension | Format | Notes |
|---|---|---|
.mp4 | MPEG-4 | Most compatible; recommended |
.m4v | MPEG-4 (Apple) | Identical to MP4; common on Apple devices |
.mov | QuickTime | Common on macOS and iOS |
.webm | WebM | Open format; browser-native |
Recorded Date Extraction
When a filename contains a parsable date (for example,2024-03-15_Warzone_highlight.mp4), Fireshare extracts that date and stores it in the recorded_at field on the Video model. This enables date-based filtering and the Browse by Date calendar view in the dashboard.
Video Metadata
Each video in the library stores the following metadata, sourced from FFprobe at scan time and editable through the UI:| Field | Description |
|---|---|
title | Display name shown in the library (defaults to filename) |
description | Optional freeform text shown on the watch page |
info | Raw JSON blob of FFprobe stream data (codec, bitrate, etc.) |
duration | Length in seconds, rounded to the nearest whole second |
width | Native horizontal resolution in pixels |
height | Native vertical resolution in pixels |
framerate | Frames per second, rounded to the nearest integer |
private | Whether the video is hidden from the public feed (default: true) |
has_480p | true when a 480p transcoded variant exists |
has_720p | true when a 720p transcoded variant exists |
has_1080p | true when a 1080p transcoded variant exists |
start_time | Crop start time in seconds (null when no crop is active) |
end_time | Crop end time in seconds (null when no crop is active) |
has_crop | true when a cropped variant has been generated |
password_hash | pbkdf2:sha256 hash; non-null when the video is password-locked |
recorded_at | Date extracted from the filename, if parsable |
Privacy Default
All newly scanned videos are marked private by default (private: True in VideoInfo). A private video is not listed in the public feed or the RSS feed, but it is still accessible to anyone who holds the direct watch link. An authenticated admin must explicitly mark a video as public for it to appear in public listings.
The global default for new videos is controlled by the
video_defaults.private key in config.json. You can change it from the Settings panel in the UI without restarting the container.Thumbnails and Animated Previews
When a video is first scanned, Fireshare runs FFmpeg to extract a single still frame and save it asposter.jpg inside the video’s derived directory (/processed/derived/<video_id>/poster.jpg).
The frame is captured at a position set by the THUMBNAIL_VIDEO_LOCATION environment variable. The value is a percentage of total duration between 0 and 100 (default: 50, i.e. the midpoint of the video).
boomerang-preview.mp4. This plays automatically when you hover over a video card in the library, giving a quick preview without opening the watch page.
Custom posters can also be uploaded per-video via POST /api/video/<video_id>/poster/custom (accepts JPEG, PNG, or WebP). The uploaded image is converted to WebP and saved as custom_poster.webp, which takes priority over the auto-generated poster.
Dashboard Views
Card View and List View
The dashboard toolbar includes a toggle between two layout modes:- Card view — a responsive grid of video thumbnails with the title, duration, and view count overlaid. Hovering a card plays the boomerang preview.
- List view — a compact table with one video per row, useful for libraries with many clips.
Sorting
The library can be sorted by any of the following options, all of which are accepted by theGET /api/videos and GET /api/videos/public endpoints via the sort query parameter:
| Sort value | Meaning |
|---|---|
updated_at desc | Newest first (default) |
updated_at asc | Oldest first |
video_info.title desc | Title Z → A |
video_info.title asc | Title A → Z |
views desc | Most viewed first |
views asc | Least viewed first |
Search
The search bar filters the visible library in real time against the following fields:- Title — partial, case-insensitive match against
VideoInfo.title - Game — partial match against the linked game name
- Tags — prefix a word with
#to filter by tag name (for example,#highlightshows only videos taggedhighlight)
View Count Tracking
Every time the watch page loads, the client sends aPOST /api/video/view request with the video_id. Fireshare records one view per unique IP address in the VideoView table (unique constraint on video_id + ip_address), so refreshing the page does not inflate the count.
View counts are returned alongside each video in the library response as view_count and are displayed on video cards and the watch page.
Date-Based Browsing
Two read-only endpoints power the Browse by Date calendar view in the dashboard:| Method | Endpoint | Description |
|---|---|---|
GET | /api/videos/dates | Returns a deduplicated list of all dates (YYYY-MM-DD) that have at least one video with a recorded_at value. Authenticated users see all dates; public users see only dates for non-private videos. |
GET | /api/videos/by-date/<date> | Returns all videos recorded on the given date (format: YYYY-MM-DD). Respects the same authentication rules. |
recorded_at field populated during the scan when a parsable date is found in the filename.
RSS Feed
Fireshare exposes a public RSS feed at/api/feed/rss that lists all videos marked as public, ordered by date. This feed is suitable for podcast clients, feed readers, or any tool that supports RSS. The feed title and description are configured via the rss_config section in config.json.
Sharing
Control public vs. private visibility and add password protection to individual videos.
Games & Tags
Organize videos by game with SteamGridDB cover art and custom cross-category tags.
Uploads
Add new videos through the browser with drag-and-drop or chunked upload.
Environment Variables
Tune scan intervals, thumbnail position, and other library-related settings.