cliprange 0.5.0

Plan media time ranges into byte ranges and fetch partial media data.

cliprange

cliprange maps media time ranges to byte ranges and provides optional fetchers for partial media workflows.

The first version focuses on MP4/M4V/MOV planning and libtorrent-based piece fetching. It is intentionally independent from QQBot, NapCat, OneBot, ZIP packaging, and chat-bot task state.

Install

For planner-only usage:

pip install cliprange

Torrent support requires the optional torrent extra:

pip install "cliprange[torrent]"

Clip extraction requires ffmpeg and ffprobe to be available on PATH.

For local development from a checkout:

pip install -e ".[dev,torrent]"

Example

from cliprange import ClipRequest, plan_mp4_clip_ranges

plan = plan_mp4_clip_ranges(
    "video.mp4",
    ClipRequest(start_seconds=600, duration_seconds=120),
)

print(plan.ranges)
print(plan.estimated_bytes)

HTTP Range Example

from cliprange import ClipRequest, HttpRangeFetcher, plan_mp4_clip_ranges

plan = plan_mp4_clip_ranges(
    "video.mp4",
    ClipRequest(start_seconds=600, duration_seconds=120),
)

fetcher = HttpRangeFetcher("https://example.com/video.mp4")
result = await fetcher.fetch_ranges(plan.ranges, "partial-video.mp4")

print(result.bytes_written)

The HTTP fetcher requires the server to support Range requests and return 206 Partial Content. It will not fall back to downloading a full file when a server ignores the Range header.

CLI

Editable installs expose three commands:

cliprange-plan video.mp4 --start 00:10:00 --duration 00:02:00
cliprange-clip video.mp4 --start 00:10:00 --duration 00:02:00 --out clip.mp4
cliprange-torrent "magnet:?xt=..." --file-largest-video --middle 120 --out clip.mp4

cliprange-torrent requires the optional torrent extra and only downloads pieces needed for the selected clip. Users are responsible for accessing only media they are authorized to use.

Real-World Smoke Test

The default test suite does not access external networks. To validate the library against a real public MP4 URL, run:

python scripts/smoke_real_world.py

The smoke script checks HTTP Range support, downloads a small public MP4, plans byte ranges, fetches those ranges, runs the CLI planner, extracts a short clip, and verifies the output duration.

To run the same check through pytest:

$env:CLIPRANGE_RUN_REAL_WORLD = "1"
pytest -m integration

Public API

The stable import surface for the current internal version is the package root:

from cliprange import (
    ByteRange,
    ClipPlan,
    ClipRangeError,
    ClipRequest,
    FfmpegError,
    HttpRangeConfig,
    HttpRangeError,
    HttpRangeFetcher,
    HttpRangeFetchResult,
    MediaRangeError,
    Mp4IndexError,
    PieceDownloadProgress,
    TorrentConfig,
    TorrentFile,
    TorrentMetadata,
    TorrentRangeError,
    TorrentRangeFetcher,
    extract_clip_to_mp4,
    is_magnet_uri,
    magnet_info_hash,
    piece_indexes_for_ranges,
    plan_mp4_clip_ranges,
    probe_duration_seconds,
    probe_piece_indexes,
    ratio_buffer_piece_indexes,
)

Internal MP4 box parsing helpers are intentionally private and may change without notice.

Scope

• MP4/M4V/MOV time range planning.
• Byte ranges to torrent piece indexes.
• HTTP Range fetching for planned byte ranges.
• Optional libtorrent metadata and piece fetching.
• Optional ffmpeg helpers for clip extraction.

Future versions may add object-storage fetchers.

Boundaries

This library does not select the "largest video", choose a default clip position, create ZIP files, upload files, store bot task state, or format chat messages. Applications should keep those decisions in their own code.

Roadmap

The plan for turning this internal prototype into a publishable library is tracked in docs/roadmap-to-1.0.md.

Documentation

• API reference
• Limitations
• Troubleshooting
• Responsible use
• Versioning
• Publishing