Export metadata

Cliparr embeds the same source identity and clip interval in video and audio exports. Available provider fields are best-effort; local files and direct URLs still receive the editor title and mandatory timing. GIF exports do not embed rich metadata.

Standard export tags

These tags are sent for every audio and video export format when the source field is available.

MP4, MOV, and M4A tags

MP4, MOV, and M4A exports also receive the current raw container keys below. Cliparr patches integer MP4 boxes so hdvd, stik, tves, and tvsn are stored as numeric metadata.

M4A receives descriptive and timing tags, including TV source information, but does not receive the video-specific hdvd or stik flags. An episode excerpt remains an episode in its source metadata. Its show title also occupies the artist slot by Cliparr convention; album and music track fields remain unset.

Shared provenance and timing

Source start and end are rounded to integer milliseconds once. Clip duration is the difference between those endpoints. The comment uses HH:MM:SS.mmm; individual timing tags use decimal seconds with three digits. These values describe the editor’s selected source interval, independently of encoder padding or the output file’s playback duration.

The named timing fields are CLIPARR_SOURCE_START_SECONDS, CLIPARR_SOURCE_END_SECONDS, CLIPARR_CLIP_DURATION_SECONDS, and CLIPARR_SOURCE_START_TIMECODE. These and the MP4 timing keys are application-defined; general players may not display them.

clpr is Cliparr’s custom metadata tag for MP4, MOV, and M4A files. It is application-defined, not a standard container metadata field. Other supported containers carry the same Cliparr-defined payload under CLIPARR_METADATA, as shown above. WAV explicitly uses an ID3 chunk so Unicode text and cover art remain supported; its provenance is stored in TXXX descriptions.

The shared payload has this shape:

{
  "version": 1,
  "source": { "itemType": "episode", "title": "Example scene" },
  "clip": {
    "sourceStartSeconds": 65.125,
    "sourceEndSeconds": 130.75,
    "durationSeconds": 65.625
  },
  "transcript": "You were the one who knocked.\nSay my name."
}

transcript is present only when the export had subtitle cues (imported subtitles or custom captions) covering the clip range. It contains text from cues that overlap the selected interval, capped at 4000 UTF-16 code units without splitting Unicode characters. Partially overlapping cues contribute their full text because cue timing does not identify individual word boundaries. The transcript is embedded even when subtitle burn-in is disabled, including audio-only exports, so dialogue can be searched with plain-text tools. GIF exports do not carry this metadata.

source also carries available source/show/season titles, season and episode numbers, date/year, descriptions, genres, studio/network, rating, and director/writer/actor credits. Artwork is embedded separately. Parsed external database IDs (externalIds.imdb, externalIds.tmdb, externalIds.tvdb) and available critic/audience scores (criticRating, audienceRating) are included. Scores use a 0-10 scale with one decimal place; missing or invalid scores are omitted. Jellyfin critic scores use a 0-100 scale and are always divided by 10. Internal provider identifiers, lookup keys, raw GUIDs, and artwork URLs are excluded.

External IDs and ratings

The version 1 JSON payload is the source of truth. Native ID tags are conveniences for tag readers. Critic and audience scores stay in JSON in every format; MP4’s rtng advisory flag is never used as a numeric score. Exports remain single files, without NFO sidecars.