adding media to your library

created 25 march 2026 2p updated 8 june 2026 7p by

freqhole has two ways to get media in: the add media modal (files/urls, one at a time or a batch) for everyday use, and directory scanning for bulk imports on a server. discovery is shared, then each file goes through its domain-specific import pipeline.

adding media (files + urls)

the add media modal (“add media” button in the app) is the everyday way to add music or video: drag files in, pick them from a file picker, or paste URLs (if url fetching is configured via [server.fetch_music]/[server.fetch_video] — see the prerequisites guide for the yt-dlp setup these rely on).

files are always added to your own local library first — reviewed there (metadata, matching, duplicates) before anything is sent anywhere. if you have a remote selected as your current target, the modal shows a target switcher and, once you’re happy with the review, sends the reviewed items to that remote next. staying purely local (no remote selected) is also fine — nothing is sent anywhere in that case.

this two-step (local first, then send) is deliberate: it means you always get to review/fix metadata against your own fast local copy, and a flaky network mid-upload never leaves your library in a half-imported state.

sending existing media to a friend

for media that’s already in your library, the share modal’s “send to remote” section pushes it to a friend’s remote (or your own charnel-managed local library) directly — no need to re-add it via files/urls. it lists every eligible destination with a live status badge (checking / offline / needs login / ready) and shows how much of the content the destination already has before sending.

configuring scan directories

scan directories are passed to the scan command or selected in the desktop app — there’s no config file section for them. supported formats are configured in [media].supported_audio_formats and [media].supported_video_formats.

in desktop app

settings → library → add folder

choose music or video for the folder. the desktop command defaults to music when no domain is supplied so older callers keep their existing behavior.

running a scan

bulk-importing directories full of files (e.g. a big existing collection on a server) uses a directory scan instead of the add-media modal:

CLI

freqhole music scan --path ~/Music

despite the legacy music scan command name, this CLI path currently scans for both configured audio and video formats.

rescan all previously tracked directories:

freqhole music scan rescan

desktop app

library → scan now

web app

settings → library → scan (member/admin only)

what happens during scan

discover files: find configured audio and/or video formats in the directory
deduplicate: skip files already tracked at the same path
queue imports: create background jobs for new files
extract metadata: read music tags or probe video properties
extract images: pull embedded cover art or generate a video poster
create entities: songs link to albums + artists; videos enter the video library
index for search: make imported media available to library queries

music metadata extraction

supported tags

title, artist, album artist
album, track number, disc number
year, genre
duration, bitrate, sample rate

embedded artwork

cover art is extracted from:

ID3 APIC frames (MP3)
Vorbis METADATA_BLOCK_PICTURE (FLAC/OGG)
MP4 covr atom (M4A)

stored as blobs, deduplicated by content hash.

video metadata extraction

video imports use ffprobe to inspect the container and streams. freqhole records properties including:

duration
width + height
video + audio codecs
container format
embedded subtitle streams

the filename becomes the initial title for a scanned video. you can edit its title, content type, series, season, episode, and other library metadata after import.

generated posters

freqhole uses ffmpeg to extract a representative frame as the initial video poster. poster extraction is best-effort: a video can still import if no poster can be generated.

renditions

when video transcoding is enabled, follow-up jobs can create configured playback renditions. the original file remains the source and is not modified.

file formats

defaults are shown below; both lists are configurable.

music

format	extension	notes
MP3	.mp3	ID3v2 tags
FLAC	.flac	Vorbis comments
Ogg Vorbis	.ogg	Vorbis comments
AAC	.m4a	iTunes-style tags
WAV	.wav	limited metadata
Opus	.opus	Vorbis comments

video

format	extension	notes
MPEG-4	.mp4	common browser playback
Matroska	.mkv	may require a rendition
WebM	.webm	browser-friendly container
QuickTime	.mov	probed with ffprobe
AVI	.avi	may require a rendition

handling duplicates

freqhole tracks media files by path. if the same file is moved:

old path: shows as missing
new path: imports as new song

to clean up missing files:

freqhole maintenance cleanup-orphans

incremental vs full scan

incremental (default)

only processes new files (not in database)
fast for adding new media
does not update changed tags

rescan

freqhole music scan rescan

reprocesses all previously tracked directories
slower but ensures everything is up to date

troubleshooting

files not appearing

check:

file extension in the matching [media].supported_audio_formats or [media].supported_video_formats list?
file readable by the freqhole process?
valid media file (not corrupted)?

wrong music metadata

tags embedded in the file take priority. to fix:

update tags in the file (with Mp3tag, Picard, etc.)
run freqhole music scan rescan

or edit in the web app (overrides file tags).

wrong video metadata or missing poster

check that ffprobe and ffmpeg are installed and that their paths are configured correctly. scanned filenames provide only an initial title; edit video, series, and season metadata in the app after import.

scan is slow

normal for large libraries on first scan. subsequent scans are incremental.

tips:

exclude non-media directories
use SSD for database
reduce extensions list