mava_exchange.writer.MediaPackageWriter¶

class mava_exchange.writer.MediaPackageWriter(path: str | Path, description: str = '')¶

Write a .mediapkg archive incrementally.

Use as a context manager (recommended) or call .write() manually.

Example

with MediaPackageWriter("out.mediapkg") as w:
    w.add_video("v1", "https://example.org/v1.mp4")
    w.add_track("v1", my_track, my_df)

Multiple videos can be added before writing:

writer = MediaPackageWriter("corpus.mediapkg")
for video_id, src, tracks_and_dfs in my_videos:
    writer.add_video(video_id, src)
    for track, df in tracks_and_dfs:
        writer.add_track(video_id, track, df)
writer.write()

__init__(path: str | Path, description: str = '')¶

Initialize writer.

Parameters:

path (str or Path) – Output path for .mediapkg file
description (str, optional) – Human-readable description of the corpus

Examples

>>> with MediaPackageWriter("output.mediapkg") as w:
        # ... add videos and tracks
        # ... and write them at the end of the block ...

Methods

`__init__`(path[, description])	Initialize writer.
`add_track`(video_id, track, df)	Add a DataFrame as a track for a video.
`add_video`(video_id, src[, title, ...])	Register a video.
`write`()	Write the .mediapkg archive to disk.

add_video(video_id: str, src: str, title: str | None = None, duration_seconds: float | None = None) → MediaPackageWriter¶

Parameters:

video_id (str) – Unique identifier for this video
src (str) – URI or path to the video file
title (str, optional) – Human-readable title
duration_seconds (float, optional) – Video duration in seconds

Returns:

Self for method chaining

Return type:

MediaPackageWriter

Raises:

ValueError – If video_id already exists

Examples

>>> with MediaPackageWriter("output.mediapkg", "A sample media corpus") as w:
        w.add_video("video_001", "https://example.org/video.mp4")

add_track(video_id: str, track: ObservationSeries | AnnotationSeries | AnnotationListSeries, df: DataFrame) → MediaPackageWriter¶

Add a DataFrame as a track for a video.

The DataFrame must contain the columns declared by the track. If the same track name is used across multiple videos, the track definition must be identical (checked automatically).

Parameters:

video_id (str) – Video identifier (must be added first with add_video)
track (Track) – Track definition (ObservationSeries, AnnotationSeries, or AnnotationListSeries)
df (pd.DataFrame) – Data with columns matching track.columns

Returns:

Self for method chaining

Return type:

MediaPackageWriter

Raises:

ValueError – If video_id not found, track definition conflicts, or columns missing

Examples

>>> with MediaPackageWriter("output.mediapkg") as w:
        w.add_track("video_001", emotions, emotions_df)

write()¶

Write the .mediapkg archive to disk.

Raises:: ValueError – If no videos have been added

Examples

>>> with MediaPackageWriter("output.mediapkg") as w:
        # ... add videos and tracks ...
        w.write()