Media management

File details, search, filters, sorting, tags and collections, where each file is used, relinking missing files, and proxies for heavy footage.

The Project bin knows each file's details and helps find, group and track footage. Everything here is organization: none of it changes what plays or exports.

Metadata. The editor reads every file in media/ and library/ with ffprobe (via GET /api/media-info) and writes what it finds onto the media entry. These fields are read-only - they describe the file:

Without ffprobe on PATH only size is filled in; the browser still probes duration, width and height.

Organizing. favorite: true stars a file; tags is a list of free-form labels (at most 24, each up to 32 characters, matched without regard to case). collections at the top of the document group media across folders - a file can be in any number of them, while it sits in one folder (folderId).

Usage. A file's placements are the clips that show it, on the main timeline and inside every composition. A video and the audio stems linked to it count as one placement, so a shot used twice reads "used 2×".

In the editor, the Project tab has:

• Search - every word must match the name, kind, extension, codec, resolution (3840x2160, 2160p) or a tag; #word matches tags only. Esc clears it.
• Show - All media · ★ Favorites · Used in the edit · Unused · a kind · a collection · a tag. While searching or filtering, the bin lists the hits flat (each with its folder), with a count and Clear; a collection's view also has Rename and Delete (its media stay).
• Sort - name (natural: shot 2 before shot 10), kind, duration, resolution, frame rate, codec, audio channels, file size or times used, with ↑ / ↓. Files missing a value sort last either way. Folders keep their tree; the sort applies inside each.
• ☰ List view - one row per file with columns: name, duration, resolution, FPS, codec, audio, size and uses; click a column heading to sort by it. On a narrow bin the columns drop out right to left; widen the panel to see them all.
• On each file: ☆ stars it, the uses badge opens its placements. Right-click a file → Open in Source, Find timeline instances (every placement, main timeline and comps, with track and time - click one to jump there, opening its comp if needed), Media info…, favorites, Tags…, Add to / Remove from a collection, New collection…, Remove from project.
• Right-click a clip on the timeline → Reveal in project scrolls the bin to its file (or its comp), opening folders and clearing a search that hides it.

Offline media. A file is offline when its src names nothing under media/ or library/ - it was moved, renamed or deleted. The editor checks on load and whenever those folders change. An offline file's clips stay where they are: the timeline hatches them red (⚠ Offline), the monitor and the export draw a Media offline slate in the picture's place, and its audio is silent. The bin marks the file OFFLINE, says how many are missing, and the Show filter gains ⚠ Offline. The Export dialog warns before rendering one. Files under media/ may sit in subfolders (/media/archive/a.mp4).

• Relink points a media entry at the same footage where it is now; clips keep their In points, edits and everything else. Right-click the file → Relink… (or Relink… on the offline banner for all of them). The dialog looks through media/ and library/ for each file - same name, the same name with another extension, a similar name, the same size - and picks a same-name match for you. Browse… picks one file and Choose folder… matches a whole folder by name; either copies the chosen files into media/. A relinked file whose length differs from the original gets a warning (is it really the same footage?).
• Replace file… (right-click a file) puts a different file behind the media entry - a new render, a better take. Every clip using it switches; each keeps its In point and timing, trimmed to fit a shorter file. The name and details follow the new file; favorites, tags and collections stay. To swap the file of one clip only, use the Inspector's Source menu instead.
• Relink and replace are one undo step each.

Proxies. Heavy footage - 4K, HEVC, ProRes, long phone clips - can stutter while you scrub and play. A proxy is a light copy the editor plays instead while you edit: H.264 at 540p (or 720p / 1080p, never larger than the source), a keyframe every 12 frames so seeking is quick, the source's own timestamps (frame for frame - no frames added or dropped) and its first audio stream. The edit always refers to the original: the timeline, project.json and every clip stay the same whether proxies are on or off.

Export always reads the originals, and so do fablecut_frame (timeline mode), fablecut_scopes, tracking and every other measurement - the players switch to the original files for the render and back afterwards. A proxy only changes how smoothly the preview runs, never the result.

• Right-click a video in the bin → Create proxy (540p) / (720p); right-click the Project tab → Create proxies for N videos. ffmpeg makes them on the server one at a time in the background; the bin shows each file's progress (P 42%), then a green P once it is ready. Delete proxy removes one. The bin's list view has a Proxy column, Show has Has a proxy / Video without a proxy, and Media info says which file is playing.
• The monitor's Proxy button turns proxy playback on and off (on by default; remembered in this browser). The Source monitor follows it too.
• Proxies live in analysis/proxies/, a disposable cache: each is named after its source file and that file's size and modification time, so a re-rendered or replaced original simply has no proxy until you make a new one. Deleting the folder loses nothing but time. Proxies need ffmpeg.

Agents:

• {op:"updateMedia", id | ids, set:{name?, favorite?, tags?, folderId?}, addTags?, removeTags?} - organize files (favorite:false unstars; tags:[] clears). Metadata keys are refused: they come from the file.
• {op:"setCollection", id?, name?, media?, add?, remove?} creates a collection (a new id, or a name no collection has) or changes one: media replaces its list, add / remove edit it. {op:"removeCollection", id} deletes it; its media stay. removeMedia takes a file out of every collection.
• The compact view lists each file with its metadata, ★, tags, folder and uses:N, and the collections on one line: m_abc video "intro.mp4" 12.4s 1920×1080 29.97 fps h264 stereo 48 kHz 45 MB ★ #interview uses:2.
• fablecut_import_media probes the file as it imports it, so the entry it returns already has these fields.
• fablecut_status lists offline media, and the compact view marks each OFFLINE (file missing — relinkMedia) and each video with a proxy proxy:540p.
• fablecut_proxy {} reports every video's proxy; {create:true, mediaIds?, height?} makes them (waits until done unless wait:false); {delete:true, mediaIds?} removes them. Proxies never change what you measure or export, so an agent only needs them when the user asks for smoother playback.
• {op:"relinkMedia", id, src:"/media/…", name?} - the same footage found elsewhere: put the file in media/ (copy it, or fablecut_import_media and removeMedia the extra entry it registers), then relink. The note warns when the new file's length differs.
• {op:"replaceMedia", id, src, name?} - a different file behind the entry; clips keep their timing, trimmed to fit (the note says how many). src must be an existing file under /media/ or /library/ of the same kind (an audio entry may use a video container).