reprostim.bids.media

BIDS media-file metadata API helpers.

Intended to provide the shared BIDS media-file field table and AudioInfo/VideoInfo -> BIDS-dict mapping helpers, per the BEP044/media-files proposal (bids-standard/bids-specification PR #2367): https://bids-specification–2367.org.readthedocs.build/en/2367/appendices/media-files.html

See .ai/bids/media-spec.md for the full specification.

Functions

parse_bids_media_info(path)

Determine a BidsMediaInfo from a file path, by name only (no filesystem access).

Classes

AudioFormat(value)

Audio file format, identified by its file extension (without the leading dot), per the BEP044/media-files proposal (bids-standard/bids-specification PR #2367).

BidsMediaCodec(value)

Common codec reference, per the BEP044/media-files proposal's Codec Identification section (bids-standard/bids-specification PR #2367).

BidsMediaErrorCode(value)

Category of problem that can be detected while determining a BidsMediaInfo from a file path.

BidsMediaInfo(*, path, media_type, format, ...)

BIDS media type/format info derived from a file path, per the BEP044/media-files proposal.

BidsMediaInfoError(*, code, message)

A single problem detected while determining a BidsMediaInfo from a file path.

BidsMediaProperty(value)

BIDS media-file sidecar metadata property, per the BEP044/media-files proposal (bids-standard/bids-specification PR #2367).

BidsMediaType(value)

BIDS media-file suffix, per the BEP044/media-files proposal (bids-standard/bids-specification PR #2367).

ImageFormat(value)

Image file format, identified by its file extension (without the leading dot), per the BEP044/media-files proposal (bids-standard/bids-specification PR #2367).

VideoFormat(value)

Video container format, identified by its file extension (without the leading dot), per the BEP044/media-files proposal (bids-standard/bids-specification PR #2367).
class reprostim.bids.media.AudioFormat(value)[source]

Audio file format, identified by its file extension (without the leading dot), per the BEP044/media-files proposal (bids-standard/bids-specification PR #2367).

AAC = 'aac'

An Advanced Audio Coding audio file.

FLAC = 'flac'

A FLAC lossless audio file.

MP3 = 'mp3'

An MP3 audio file.

OGG = 'ogg'

An Ogg audio file, typically containing Vorbis-encoded audio.

WAV = 'wav'

A Waveform Audio File Format audio file, typically containing uncompressed PCM audio.

class reprostim.bids.media.BidsMediaCodec(value)[source]

Common codec reference, per the BEP044/media-files proposal’s Codec Identification section (bids-standard/bids-specification PR #2367). Each member’s value is the FFmpeg codec name — the RECOMMENDED value for the AudioCodec/VideoCodec fields, auto-extractable via ffprobe -v quiet -print_format json -show_streams <file>. rfc6381 is a representative RFC 6381 codec string (OPTIONAL; used for AudioCodecRFC6381/ VideoCodecRFC6381 — actual strings vary by profile/level, so this is only an example value), and category is the BidsMediaType stream kind (AUDIO or VIDEO) the codec applies to.

Not exhaustive: AudioCodec/VideoCodec accept any FFmpeg codec name as a free string; this enum only covers the common codecs listed in the BEP044 reference table.

AAC = 'aac'

AAC-LC. Default audio for MP4.

AV1 = 'av1'

AV1. Next-gen open codec.

FLAC = 'flac'

FLAC. Open lossless audio.

H264 = 'h264'

H.264 / AVC. Most widely supported.

HEVC = 'hevc'

H.265 / HEVC. High efficiency.

MP3 = 'mp3'

MP3. Legacy lossy audio.

OPUS = 'opus'

Opus. Open, low-latency audio.

PCM_S16LE = 'pcm_s16le'

PCM 16-bit LE. Uncompressed (WAV). No RFC 6381 string.

VP9 = 'vp9'

VP9. Open, royalty-free.

classmethod for_category(category: BidsMediaType) → List[BidsMediaCodec][source]

Return all codecs applicable to the given stream category (AUDIO or VIDEO).

class reprostim.bids.media.BidsMediaErrorCode(value)[source]

Category of problem that can be detected while determining a BidsMediaInfo from a file path. Populated by a separate path-parsing module function (not part of this data class).

INVALID_PATH = 'invalid_path'

The given path is malformed or has no filename/extension.

MEDIA_TYPE_MISMATCH = 'media_type_mismatch'

The file extension is inconsistent with the detected/declared media type (e.g. an audio-only extension on a _video file).

UNKNOWN_EXTENSION = 'unknown_extension'

The file extension is not a recognized Audio/Video/Image format.

UNKNOWN_MEDIA_TYPE = 'unknown_media_type'

The BIDS media type could not be determined from the path.

class reprostim.bids.media.BidsMediaInfo(*, path: str, media_type: ~reprostim.bids.media.BidsMediaType | None = None, format: ~reprostim.bids.media.AudioFormat | ~reprostim.bids.media.VideoFormat | ~reprostim.bids.media.ImageFormat | None = None, errors: ~typing.List[~reprostim.bids.media.BidsMediaInfoError] = <factory>)[source]

BIDS media type/format info derived from a file path, per the BEP044/media-files proposal. Pure data holder — populated by a separate path-parsing module function, not a method on this class.

errors: List[BidsMediaInfoError]
format: AudioFormat | VideoFormat | ImageFormat | None
media_type: BidsMediaType | None
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

path: str
property valid: bool

True when no errors were detected.

class reprostim.bids.media.BidsMediaInfoError(*, code: BidsMediaErrorCode, message: str)[source]

A single problem detected while determining a BidsMediaInfo from a file path.

code: BidsMediaErrorCode
message: str
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class reprostim.bids.media.BidsMediaProperty(value)[source]

BIDS media-file sidecar metadata property, per the BEP044/media-files proposal (bids-standard/bids-specification PR #2367). Each member’s value is the exact sidecar JSON key; categories lists the BidsMediaType suffix(es) the property applies to, so properties can be filtered by category via for_category().

AUDIO_BIT_DEPTH = 'AudioBitDepth'

Number of bits per sample in the audio stream.

AUDIO_CHANNEL_COUNT = 'AudioChannelCount'

Number of audio channels.

AUDIO_CODEC = 'AudioCodec'

Audio codec as FFmpeg name (e.g. “aac”, “mp3”, “opus”).

AUDIO_CODEC_RFC6381 = 'AudioCodecRFC6381'

Audio codec as an RFC 6381 string (e.g. “mp4a.40.2” for AAC-LC).

AUDIO_SAMPLE_RATE = 'AudioSampleRate'

Sampling frequency of the audio stream, in Hz.

IMAGE_BIT_DEPTH = 'ImageBitDepth'

Bit depth per channel of the stored pixel data.

IMAGE_HEIGHT = 'ImageHeight'

Height of the video frame or image, in pixels.

IMAGE_PIXEL_FORMAT = 'ImagePixelFormat'

Pixel format per FFmpeg pix_fmt (e.g. “yuv420p”, “rgb24”).

IMAGE_WIDTH = 'ImageWidth'

Width of the video frame or image, in pixels.

RECORDING_DURATION = 'RecordingDuration'

Length of the recording in seconds.

VIDEO_CODEC = 'VideoCodec'

Video codec as FFmpeg name (e.g. “h264”, “hevc”, “vp9”).

VIDEO_CODEC_RFC6381 = 'VideoCodecRFC6381'

Video codec as an RFC 6381 string (e.g. “avc1.640028” for H.264).

VIDEO_FRAME_COUNT = 'VideoFrameCount'

Total number of frames in the video stream.

VIDEO_FRAME_RATE = 'VideoFrameRate'

Video frame rate of the video stream, in Hz.

classmethod for_category(category: BidsMediaType) → List[BidsMediaProperty][source]

Return all properties that apply to the given media category.

class reprostim.bids.media.BidsMediaType(value)[source]

BIDS media-file suffix, per the BEP044/media-files proposal (bids-standard/bids-specification PR #2367).

AUDIO = 'audio'

An audio data file containing one or more audio streams. Common formats include WAV (uncompressed), MP3, AAC, and Ogg Vorbis.

AUDIOVIDEO = 'audiovideo'

A media file containing both audio and video streams. Common containers include MP4, MKV, AVI, and WebM.

IMAGE = 'image'

A still image data file. Common formats include JPEG, PNG, SVG, WebP, and TIFF.

VIDEO = 'video'

A video data file containing one or more video streams but no audio. Common containers include MP4, MKV, AVI, and WebM.

class reprostim.bids.media.ImageFormat(value)[source]

Image file format, identified by its file extension (without the leading dot), per the BEP044/media-files proposal (bids-standard/bids-specification PR #2367).

JPG = 'jpg'

A JPEG image file.

PNG = 'png'

A Portable Network Graphics file.

SVG = 'svg'

A Scalable Vector Graphics image file.

TIF = 'tif'

A Tag Image File Format file.

TIFF = 'tiff'

A Tag Image File Format image file. The .tiff extension is the long form of .tif.

WEBP = 'webp'

A WebP image file.

class reprostim.bids.media.VideoFormat(value)[source]

Video container format, identified by its file extension (without the leading dot), per the BEP044/media-files proposal (bids-standard/bids-specification PR #2367).

AVI = 'avi'

An Audio Video Interleave media container file.

MKV = 'mkv'

A Matroska media container file.

MP4 = 'mp4'

An MPEG-4 Part 14 media container file.

WEBM = 'webm'

A WebM media container file, typically containing VP8/VP9 video and Vorbis/Opus audio.

reprostim.bids.media.parse_bids_media_info(path: str) → BidsMediaInfo[source]

Determine a BidsMediaInfo from a file path, by name only (no filesystem access).

The BIDS media type is primarily read from the filename’s trailing _<suffix> token (e.g. ..._video.mkv -> BidsMediaType.VIDEO). If that token is missing or not a valid BidsMediaType value, a UNKNOWN_MEDIA_TYPE error is recorded and the media type is instead guessed from the file extension (see _media_type_from_format()). The file extension is always independently resolved to a format (AudioFormat/VideoFormat/ImageFormat); an unrecognized extension is recorded as an UNKNOWN_EXTENSION error regardless of whether the media type was resolved from the filename suffix.