The swiss army knife of lossless video/audio editing
// FFProbe response types. Copied from https://gist.github.com/termermc/2a62735201cede462763456542d8a266
// See also https://github.com/DefinitelyTyped/DefinitelyTyped/blob/a21bbc63c5a31afbad57c3830582c389d32a931b/types/ffprobe/index.d.ts#L4
// These definitions are my best attempt at documenting the output of FFprobe using the "-print_format json" option
// The descriptions come mostly out of experience, deduction, and the very sparse documentation of the outputs
// Not all fields will be present (it depends on the file), but fields that are definite are not marked as optional
// Sample probe:
// ffprobe -v quiet -print_format json -show_format -show_streams -show_chapters -show_error my_file.mp4
/**
@typedef FFprobeDisposition
@property {number} default 1 if the default track
@property {number} dub 1 if a dub track
@property {number} original 1 if the original track
@property {number} comment 1 if a comment track
@property {number} lyrics 1 if a lyrics track
@property {number} karaoke 1 if a karaoke track
@property {number} forced 1 if a forced track
@property {number} hearing_impaired 1 if a track for the hearing impaired
@property {number} visual_impaired 1 if a track for the visually impaired
@property {number} clean_effects 1 if a clean effects track (meaning not entirely understood)
@property {number} attached_pic 1 if an attached picture track
@property {number} timed_thumbnails 1 if a timed thumbnails track (perhaps like the preview thumbnails you get when scrolling over a YouTube video's seek bar)
@property {number} captions 1 if a captions track
@property {number} descriptions 1 if a descriptions track
@property {number} metadata 1 if a metadata track
@property {number} dependent 1 if a dependent track (unclear meaning)
@property {number} still_image 1 if a still image track
*/
/**
@typedef FFprobeStreamTags
@property {string} [language] The track's language code (usually represented using a 3 letter language code, e.g.: "eng")
@property {string} [handler_name] The name of the handler which produced the track
@property {string} [vendor_id] The ID of the vendor which produced the track
@property {string} [encoder] The name of the encoder responsible for creating the stream
@property {string} [creation_time] The date (often ISO-formatted, but it may use other formats) when the media was created
@property {string} [comment] The comment attached to the stream
*/
/**
@typedef FFprobeStream
@property {number} index The stream index
@property {string} codec_name The codec's name
@property {string} codec_long_name The codec's long (detailed) name
@property {string} profile The codec profile
@property {'video'|'audio'|'subtitle'} codec_type The type of codec (video, audio, subtitle, etc)
@property {string} codec_tag_string The codec tag (technical name)
@property {string} codec_tag The codec tag ID
@property {string} [sample_fmt] The audio sample format (not present if codec_type is not "audio")
@property {string} [sample_rate] A string representation of an integer showing the audio sample rate (not present if codec_type is not "audio")
@property {number} [channels] The audio track's channel count (not present if codec_type is not "audio")
@property {string} [channel_layout] The audio track's channel layout (e.g. "stereo") (not present if codec_type is not "audio")
@property {number} [bits_per_sample] Bits per audio sample (might not be accurate, may just be 0) (not present if codec_type is not "audio")
@property {number} [width] The video stream width (also available for images) (not present if codec_type is not "video")
@property {number} [height] The stream height (also available for images) (not present if codec_type is not "video")
@property {number} [coded_width] The stream's coded width (shouldn't vary from "width") (not present if codec_type is not "video")
@property {number} [coded_height] The stream's coded height (shouldn't vary from "height") (not present if codec_type is not "video")
@property {number} [closed_captions] Set to 1 if closed captions are present in stream... I think (not present if codec_type is not "video")
@property {number} [has_b_frames] Set to 1 if the stream has b-frames... I think (not present if codec_type is not "video")
@property {string} [sample_aspect_ratio] The sample aspect ratio (you probably want "display_aspect_ratio") (not present if codec_type is not "video")
@property {string} [display_aspect_ratio] The display (real) aspect ratio (e.g. "16:9") (not present if codec_type is not "video")
@property {string} [pix_fmt] The pixel format used (not present if codec_type is not "video")
@property {number} [level] Unknown (not present if codec_type is not "video")
@property {string} [color_range] The color range used (e.g. "tv") (not present if codec_type is not "video")
@property {string} [color_space] The color space used (not present if codec_type is not "video")
@property {string} [color_transfer] The color transfer used (not present if codec_type is not "video")
@property {string} [color_primaries] The color primaries used (not present if codec_type is not "video")
@property {string} [chroma_location] The chroma location (not present if codec_type is not "video")
@property {number} [refs] Unknown (not present if codec_type is not "video")
@property {'true'|'false'} [is_avc] Whether the stream is AVC (not present if codec_type is not "video")
@property {string} [nal_length_size] Unknown string representing a number (not present if codec_type is not "video")
@property {string} r_frame_rate Odd formatting of the frame rate, possibly "real frame rate"? (e.g. "30/1")
@property {string} avg_frame_rate Odd formatting of the average frame rate (e.g. "30/1")
@property {string} time_base The division equation to use for converting integer representations of timestamps into seconds (e.g. "1/30000" turns 80632552 into 2687.751733 seconds)
@property {number} start_pts Unknown
@property {string} start_time A string representation of a floating point integer showing the start time in seconds
@property {number} duration_ts The stream's duration in integer timestamp format (defined by time_base)
@property {string} duration A string representation of a floating point integer showing the stream duration in seconds
@property {string} [bit_rate] The string representation of an integer showing the stream bit rate (not present on lossless formats such as FLAC)
@property {string} [bits_per_raw_sample] A string representation of an integer showing the bits per raw sample (not present if codec_type is not "video")
@property {string} nb_frames A string representation of an integer showing the total number of frames in the stream
@property {FFprobeDisposition} disposition The stream's disposition
@property {FFprobeStreamTags} [tags] The stream's tags
*/
/**
@typedef FFprobeChapterTags
@property {string} title The chapter title
*/
/**
@typedef FFprobeChapter
@property {number} id The chapter ID
@property {string} time_base The division equation to use for converting integer representations of timestamps into seconds (e.g. "1/30000" turns 80632552 into 2687.751733 seconds)
@property {number} start When the chapter starts in integer timestamp format (defined by time_base)
@property {string} start_time The string representation of a floating point integer showing when the chapter starts in seconds
@property {number} end When the chapter end in integer timestamp format (defined by time_base)
@property {string} end_time The string representation of a floating point integer showing when the chapter ends in seconds
@property {FFprobeChapterTags} tags The chapter's tags
*/
/**
@typedef FFprobeFormatTags
@property {string} major_brand Not clear, probably the media type brand, but not sure
@property {string} minor_version The brand version perhaps, but not sure
@property {string} compatible_brands The brands that are compatible with the referenced brands perhaps, but not sure
@property {string} [title] The media's title (song metadata uses an all uppercase version)
@property {string} [artist] The media artist (song metadata uses an all uppercase version)
@property {string} [date] The media's creation date, seems to be in YYYYMMDD format (song metadata uses an all uppercase version)
@property {string} [encoder] The name of the encoder responsible for encoding the media
@property {string} [comment] The comment attached to the file
@property {string} [description] The description attached to the file
@property {string} [creation_time] The ISO-formatted date (although it may use other formats) when the media was created
@property {string} [ALBUM] The album (only present in audio files)
@property {string} [album_artist] The album arist (only present in audio files)
@property {string} [ALBUMARTISTSORT] The album artist name used for sorting probably (only present in audio files)
@property {string} [ARTIST] The song artist (only present in audio files)
@property {string} [DATE] The date when the song was created (no particular format, often the year) (only present in audio files)
@property {string} [disc] The string representation of an integer showing the song's disc number (only present in audio files)
@property {string} [DISCTOTAL] The string representation of an integer showing the total number of discs comprising the album the song is in (only present in audio files)
@property {string} [ISRC] The song's International Standard Recording Code
@property {string} [GENRE] The song's genre (only present in audio files)
@property {string} [TITLE] The song's title (only present in audio files)
@property {string} [track] The string representation of an integer showing the song's track number (only present in audio files)
@property {string} [TRACKTOTAL] The string representation of an integer showing the total number of tracks in the album the song is in (only present in audio files)
@property {string} [YEAR] The string representation of an integer showing the year the song was created (only present in audio files)
@property {string} [BPM] The string representation of an integer showing the song's BPM (only present in audio files)
@property {string} [PUBLISHER] The song's publisher (only present in audio files)
*/
/**
@typedef FFprobeFormat
@property {string} filename The path of the probed file (as specified in the input file argument)
@property {number} nb_streams The total number of streams present
@property {number} nb_programs The total number of programs present
@property {string} format_name The name of the format (a comma separated list of applicable file extensions for the format)
@property {string} format_long_name The long (detailed) name of the format
@property {string} start_time The string representation of a floating point integer showing the file's starting time
@property {string} duration The string representation of a floating point integer showing the file's duration in seconds (seems to be a non-accurate, rounded version of the real duration)
@property {string} size The string representation of a long integer showing the file's size in bytes
@property {string} bit_rate The string representation of a long integer showing the file's stated bitrate (may vary between streams, probably applies to just video if a video file)
@property {number} probe_score A score of how confident FFprobe is of the format, 0 to 100. https://stackoverflow.com/questions/25257986/what-does-probe-score-mean-in-ffprobe-output
@property {FFprobeFormatTags} [tags] The format's tags
*/
/**
@typedef FFprobeProbeError
@property {number} code The error code
@property {string} string The error message
*/
/**
@typedef FFprobeProbeResult
@property {Array<FFprobeStream>} [streams] The probed file's streams (-show_streams flag required)
@property {Array<FFprobeChapter>} [chapters] The probed file's chapters (-show_chapters flag required)
@property {FFprobeFormat} [format] The probed file's format data (-show_format flag required)
@property {FFprobeProbeError} [error] The error that occurred when trying to probe the file (-show_error flag required)
*/
/** The "disposition" field on an FFprobe response stream object */
export interface FFprobeStreamDisposition {
/** 1 if the default track */
default: 1 | 0,
/** 1 if a dub track */
dub: 1 | 0,
/** 1 if the original track */
original: 1 | 0,
/** 1 if a comment track */
comment: 1 | 0,
/** 1 if a lyrics track */
lyrics: 1 | 0,
/** 1 if a karaoke track */
karaoke: 1 | 0,
/** 1 if a forced track */
forced: 1 | 0,
/** 1 if a track for the hearing impaired */
hearing_impaired: 1 | 0,
/** 1 if a track for the visually impaired */
visual_impaired: 1 | 0,
/** 1 if a clean effects track */
clean_effects: 1 | 0,
/** 1 if an attached picture track */
attached_pic: 1 | 0,
/** 1 if a timed thumbnails track (perhaps like the preview thumbnails you get when scrolling over a YouTube video's seek bar) */
timed_thumbnails: 1 | 0,
/** 1 if a captions track */
captions: 1 | 0,
/** 1 if a descriptions track */
descriptions: 1 | 0,
/** 1 if a metadata track */
metadata: 1 | 0,
/** 1 if a dependent track (unclear meaning) */
dependent: 1 | 0,
/** 1 if a still image track */
still_image: 1 | 0
}
/** The "tags" field on an FFprobe response stream object */
export type FFprobeStreamTags = {
/** The track's language (usually represented using a 3 letter language code, e.g.: "eng") */
language?: string,
/** The name of the handler which produced the track */
handler_name?: string,
/** The ID of the vendor which produced the track */
vendor_id?: string,
/** The name of the encoder responsible for creating the stream */
encoder?: string,
/** The date (often ISO-formatted, but it may use other formats) when the media was created */
creation_time?: string,
/** The comment attached to the stream */
comment?: string
rotate?: string,
// https://github.com/mifi/lossless-cut/issues/1530
title?: string,
} & Record<string, string>;
/** An FFprobe response stream object */
export interface FFprobeStream {
/** The stream index */
index: number,
/** The codec's name */
codec_name: string,
/** The codec's long (detailed) name */
codec_long_name: string,
/** The codec profile */
profile: string,
/** The type of codec (video, audio, subtitle, etc.) */
codec_type: 'video' | 'audio' | 'subtitle' | 'attachment' | 'data',
/** The codec tag (technical name) */
codec_tag_string: string,
/** The codec tag ID */
codec_tag: string,
/** The audio sample format (not present if codec_type is not "audio") */
sample_fmt?: string,
/** A string representation of an integer showing the audio sample rate (not present if codec_type is not "audio") */
sample_rate?: string,
/** The audio track's channel count (not present if codec_type is not "audio") */
channels?: number,
/** The audio track's channel layout (e.g. "stereo") (not present if codec_type is not "audio") */
channel_layout?: string,
/** Bits per audio sample (might not be accurate, may just be 0) (not present if codec_type is not "audio") */
bits_per_sample?: number,
/** The video stream width (also available for images) (not present if codec_type is not "video") */
width?: number,
/** The stream height (also available for images) (not present if codec_type is not "video") */
height?: number,
/** The stream's coded width (shouldn't vary from "width") (not present if codec_type is not "video") */
coded_width?: number,
/** The stream's coded height (shouldn't vary from "height") (not present if codec_type is not "video") */
coded_height?: number,
/** Set to 1 if closed captions are present in stream... I think (not present if codec_type is not "video") */
closed_captions?: 1 | 0 | number,
/** Set to 1 if the stream has b-frames... I think (not present if codec_type is not "video") */
has_b_frames?: 1 | 0 | number,
/** The sample aspect ratio (you probably want "display_aspect_ratio") (not present if codec_type is not "video") */
sample_aspect_ratio?: string,
/** The display (real) aspect ratio (e.g. "16:9") (not present if codec_type is not "video") */
display_aspect_ratio?: string,
/** The pixel format used (not present if codec_type is not "video") */
pix_fmt?: string,
/** Unknown (not present if codec_type is not "video") */
level?: number,
/** The color range used (e.g. "tv") (not present if codec_type is not "video") */
color_range?: string,
/** The color space used (not present if codec_type is not "video") */
color_space?: string,
/** The color transfer used (not present if codec_type is not "video") */
color_transfer?: string,
/** The color primaries used (not present if codec_type is not "video") */
color_primaries?: string,
/** The chroma location (not present if codec_type is not "video") */
chroma_location?: string,
/** Unknown (not present if codec_type is not "video") */
refs?: number,
/** Whether the stream is AVC (not present if codec_type is not "video") */
is_avc?: 'true' | 'false',
/** Unknown string representing a number (not present if codec_type is not "video") */
nal_length_size?: string,
/** Odd formatting of the frame rate, possibly "real frame rate"? (e.g. "30/1") */
r_frame_rate: string,
/** Odd formatting of the average frame rate (e.g. "30/1") */
avg_frame_rate: string,
/** The division equation to use for converting integer representations of timestamps into seconds (e.g. "1/30000" turns 80632552 into 2687.751733 seconds) */
time_base: string,
/** Unknown */
start_pts: number,
/** A string representation of a floating point integer showing the start time in seconds */
start_time: string,
/** The stream's duration in integer timestamp format (defined by time_base) */
duration_ts: number,
/** A string representation of a floating point integer showing the stream duration in seconds */
duration: string,
/** The string representation of an integer showing the stream bit rate (not present on lossless formats such as FLAC) */
bit_rate?: string,
/** A string representation of an integer showing the bits per raw sample (not present if codec_type is not "video") */
bits_per_raw_sample?: string,
/** A string representation of an integer showing the total number of frames in the stream */
nb_frames: string,
/** The stream's disposition */
disposition: FFprobeStreamDisposition,
/** The stream's tags */
tags?: FFprobeStreamTags
}
/** The "tags" field on an FFprobe response chapter object */
export interface FFprobeChapterTags {
/** The chapter title */
title: string
}
/** An FFprobe response chapter object */
export interface FFprobeChapter {
/** The chapter ID */
id: number,
/** The division equation to use for converting integer representations of timestamps into seconds (e.g. "1/30000" turns 80632552 into 2687.751733 seconds) */
time_base: string,
/** When the chapter starts in integer timestamp format (defined by time_base) */
start: number,
/** The string representation of a floating point integer showing when the chapter starts in seconds */
start_time: string,
/** When the chapter end in integer timestamp format (defined by time_base) */
end: number,
/** The string representation of a floating point integer showing when the chapter ends in seconds */
end_time: string,
/** The chapter's tags */
tags?: FFprobeChapterTags
}
/** The "tags" field on an FFprobe response format object */
export type FFprobeFormatTags = {
/** Not clear, probably the media type brand, but not sure */
major_brand: string,
/** The brand version perhaps, but not sure */
minor_version: string,
/** The brands that are compatible with the referenced brands perhaps, but not sure */
compatible_brands: string,
/** The media's title (song metadata uses an all uppercase version) */
title?: string,
/** The media artist (song metadata uses an all uppercase version) */
artist?: string,
/** The media's creation date, seems to be in YYYYMMDD format (song metadata uses an all uppercase version) */
date?: string,
/** The name of the encoder responsible for encoding the media */
encoder?: string,
/** The comment attached to the file */
comment?: string,
/** The description attached to the file */
description?: string,
/** The ISO-formatted date (although it may use other formats) when the media was created */
creation_time?: string,
/** The album (only present in audio files) */
ALBUM?: string,
/** The album arist (only present in audio files) */
album_artist?: string,
/** The album artist name used for sorting probably (only present in audio files) */
ALBUMARTISTSORT?: string,
/** The song artist (only present in audio files) */
ARTIST?: string,
/** The date when the song was created (no particular format, often the year) (only present in audio files) */
DATE?: string,
/** The string representation of an integer showing the song's disc number (only present in audio files) */
disc?: string,
/** The string representation of an integer showing the total number of discs comprising the album the song is in (only present in audio files) */
DISCTOTAL?: string,
/** The song's International Standard Recording Code */
ISRC?: string,
/** The song's genre (only present in audio files) */
GENRE?: string,
/** The song's title (only present in audio files) */
TITLE?: string,
/** The string representation of an integer showing the song's track number (only present in audio files) */
track?: string,
/** The string representation of an integer showing the total number of tracks in the album the song is in (only present in audio files) */
TRACKTOTAL?: string,
/** The string representation of an integer showing the year the song was created (only present in audio files) */
YEAR?: string,
/** The string representation of an integer showing the song's BPM (only present in audio files) */
BPM?: string,
/** The song's publisher (only present in audio files) */
PUBLISHER?: string
} & Record<string, string>;
/** An FFprobe response format object */
export interface FFprobeFormat {
/** The path of the probed file (as specified in the input file argument) */
filename: string,
/** The total number of streams present */
nb_streams: number,
/** The total number of programs present */
nb_programs: number,
/** The name of the format (a comma separated list of applicable file extensions for the format) */
format_name: string,
/** The long (detailed) name of the format */
format_long_name: string,
/** The string representation of a floating point integer showing the file's starting time */
start_time: string,
/** The string representation of a floating point integer showing the file's duration in seconds (seems to be a non-accurate, rounded version of the real duration) */
duration: string,
/** The string representation of a long integer showing the file's size in bytes */
size: string,
/** The string representation of a long integer showing the file's stated bitrate (may vary between streams, probably applies to just video if a video file) */
bit_rate: string,
/** A score of how confident FFprobe is of the format, 0 to 100. https://stackoverflow.com/questions/25257986/what-does-probe-score-mean-in-ffprobe-output */
probe_score: number,
/** The format's tags */
tags?: FFprobeFormatTags
}
/** An FFprobe error object */
export interface FFprobeProbeError {
/** The error code */
code: number,
/** The error message */
string: string
}
/** An FFprobe probe result object */
export interface FFprobeProbeResult {
/** The probed file's streams (-show_streams flag required) */
streams?: FFprobeStream[],
/** The probed file's chapters (-show_chapters flag required) */
chapters?: FFprobeChapter[],
/** The probed file's format data (-show_format flag required) */
format?: FFprobeFormat,
/** The error that occurred when trying to probe the file (-show_error flag required) */
error?: FFprobeProbeError
}