API Reference

Cropbox is primarily an application, not a large public library surface. The most useful Python-facing entrypoints today are the CLI launcher, the desktop app launcher, and the headless export and probing helpers.

Package Version

cropbox.__version__

Current package version string.

Desktop Entry Point

cropbox.app.main(initial_media=None, initial_trim=None, initial_crop=None, initial_position=None) -> int

Creates the Qt application, applies the Cropbox theme, opens the main window, and starts the event loop.

Supporting model types:

• cropbox.models.trim_range.TrimRange
• cropbox.models.crop_rect.CropRect
• cropbox.__main__.InitialPosition

CLI Entry Point

cropbox.__main__.main() -> int

Parses command-line arguments and chooses between launching the desktop app and running a headless export.

Headless Export

cropbox.media.headless.export_media(input_path, output_path, trim_start, trim_end, crop, force=False) -> int

Runs Cropbox export validation, probes the input media, builds the FFmpeg command, and executes it.

Raises cropbox.media.headless.HeadlessExportError for validation or startup failures before FFmpeg is launched.

Media Probing

cropbox.media.probe.probe_media(path) -> MediaInfo

Uses Qt image probing for still images and ffprobe JSON output for timed media. Returns a MediaInfo record with dimensions, duration, codecs, and audio presence.

Raises cropbox.media.probe.ProbeError when FFmpeg tools are unavailable or media inspection fails.

FFmpeg Command Builder

cropbox.media.commands.build_export_command(...) -> list[str]

Builds the FFmpeg command used by both the UI export flow and the headless export path. It supports crop, transform, playback-rate, output-size, and GIF palette options.

Core Models

Useful data classes exposed under cropbox.models include:

• CropRect: source-space crop geometry
• TrimRange: trim start and end times
• TransformState: resize, rotation, and flip state
• MediaInfo: probed metadata for the current input
• EditSession: grouped editing state for a loaded asset

These types are simple building blocks and may evolve alongside the UI and export pipeline.