Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

mp4-py

PyPI SPEC 0 — Minimum Supported Dependencies image License Actions status

About Shiguredo's open source software

We will not respond to PRs or issues that have not been discussed on Discord. Also, Discord is only available in Japanese.

Please read https://github.com/shiguredo/oss/blob/master/README.en.md before use.

時雨堂のオープンソースソフトウェアについて

利用前に https://github.com/shiguredo/oss をお読みください。

mp4-py について

mp4-rust の Python バインディングです。 MP4 コンテナフォーマットの読み書きをサポートしています。

対応プラットフォーム

  • macOS 26 arm64
  • macOS 15 arm64
  • Ubuntu 24.04 x86_64 (manylinux2014 wheel は glibc 2.17+ 対応)
  • Ubuntu 24.04 arm64 (manylinux2014 wheel は glibc 2.17+ 対応)
  • Windows Server 2025 x86_64
  • Windows 11 x86_64

対応 Python

  • 3.14 (abi3 wheel: 3.12/3.13/3.14 共通)
  • 3.14t (Free-Threading, 専用 wheel)
  • 3.13 (abi3 wheel)
  • 3.12 (abi3 wheel)

インストール

uv add mp4-py

使い方(基本 API)

  • Mp4FileDemuxer / Mp4FileMuxer
  • ビデオ/オーディオ/字幕トラックの読み書きをサポート
  • Opus / AAC / FLAC 音声コーデック対応
  • VP8 / VP9 / AV1 / H.264 / H.265 映像コーデック対応
  • STPP (XML 字幕) / WVTT (WebVTT 字幕) / TX3G (3GPP タイムドテキスト) 対応
  • Python Free Threading 対応

MP4 ファイルの読み込み

import io
from mp4 import Mp4FileDemuxer

# ファイルパスから demuxer を作成
with Mp4FileDemuxer("input.mp4") as demuxer:
    # サンプルを走査して処理
    for sample in demuxer:
        print(f"Sample: {sample.timestamp_seconds}s, keyframe={sample.keyframe}")
        print(f"Data size: {len(sample.data)} bytes")

# バイナリストリームから demuxer を作成
with open("input.mp4", "rb") as fp:
    demuxer = Mp4FileDemuxer(fp)
    for sample in demuxer:
        # サンプルを処理...
        pass

MP4 ファイルの作成

import io
from mp4 import (
    Mp4FileMuxer,
    Mp4MuxSample,
    Mp4SampleEntryVp08,
)


# ファイルにマルチプレックス
with Mp4FileMuxer("output.mp4") as muxer:
    # VP8 ビデオサンプルエントリーを作成
    video_entry = Mp4SampleEntryVp08(
        width=1920,
        height=1080,
    )

    # フレームを追加
    for i in range(30):
        is_keyframe = (i % 10) == 0  # 10フレームごとにキーフレーム

        # ビデオデータ(実際のエンコード済みデータに置き換えてください)
        video_data = b'\x00' * 1000

        # サンプルを作成して追加
        sample = Mp4MuxSample(
            track_kind="video",
            sample_entry=video_entry,
            keyframe=is_keyframe,
            timescale=30,
            duration=1,
            data=video_data,
        )
        muxer.append_sample(sample)

    # finalize() を呼んでファイルを完成させる(自動的に呼ばれるが明示的に呼ぶこともできます)

# バイナリストリームにマルチプレックス
with open("output.mp4", "wb") as fp:
    with Mp4FileMuxer(fp) as muxer:
        # マルチプレックス処理...
        pass

トラック情報の取得

from mp4 import Mp4FileDemuxer

with Mp4FileDemuxer("input.mp4") as demuxer:
    for track in demuxer.tracks:
        print(f"Track ID: {track.track_id}")
        print(f"Kind: {track.kind}")  # 'video' / 'audio' / 'subtitle'
        print(f"Duration: {track.duration_seconds:.2f}s")

[!WARNING]

  • 現在は基本的な読み書き機能をサポートしています
  • マルチプレックス時は最初のサンプルで sample_entry を必須で指定してください
  • 同じトラック内で同じコーデック設定が続く場合、sample_entryNone を指定できます

サンプル

  • examples/demux.py: MP4 ファイルをデマルチプレックスしてトラックとサンプル情報を表示
  • examples/remux.py: MP4 ファイルをリマルチプレックス(読み込んで別ファイルに書き込む)

実行例:

uv run python examples/demux.py input.mp4
uv run python examples/remux.py input.mp4 output.mp4

開発ビルド

# maturin をインストール
uv pip install maturin

# 開発ビルド (editable install)
maturin develop --release

# wheel を生成
maturin build --release --out wheelhouse --generate-stubs

# テスト
uv pip install pytest pytest-timeout hypothesis
uv run pytest tests/ --timeout=30

Rust 側は crates.io の shiguredo_mp4 を通常の cargo 依存として参照している (Cargo.toml を参照)。

mp4-rust ライセンス

Apache License 2.0

Copyright 2024-2026, Takeru Ohta (Original Author)
Copyright 2024-2026, Shiguredo Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

mp4-py ライセンス

Apache License 2.0

Copyright 2025 Takeru Ohta (Original Author)
Copyright 2025 Shiguredo Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mp4_py-2026.2.0.dev2.tar.gz (110.0 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

mp4_py-2026.2.0.dev2-cp314-cp314t-win_amd64.whl (369.6 kB view details)

Uploaded CPython 3.14tWindows x86-64

mp4_py-2026.2.0.dev2-cp314-cp314t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (525.9 kB view details)

Uploaded CPython 3.14tmanylinux: glibc 2.17+ x86-64

mp4_py-2026.2.0.dev2-cp314-cp314t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (532.9 kB view details)

Uploaded CPython 3.14tmanylinux: glibc 2.17+ ARM64

mp4_py-2026.2.0.dev2-cp314-cp314t-macosx_11_0_arm64.whl (484.1 kB view details)

Uploaded CPython 3.14tmacOS 11.0+ ARM64

mp4_py-2026.2.0.dev2-cp312-abi3-win_amd64.whl (370.7 kB view details)

Uploaded CPython 3.12+Windows x86-64

mp4_py-2026.2.0.dev2-cp312-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (525.1 kB view details)

Uploaded CPython 3.12+manylinux: glibc 2.17+ x86-64

mp4_py-2026.2.0.dev2-cp312-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (532.5 kB view details)

Uploaded CPython 3.12+manylinux: glibc 2.17+ ARM64

mp4_py-2026.2.0.dev2-cp312-abi3-macosx_11_0_arm64.whl (484.9 kB view details)

Uploaded CPython 3.12+macOS 11.0+ ARM64

File details

Details for the file mp4_py-2026.2.0.dev2.tar.gz.

File metadata

  • Download URL: mp4_py-2026.2.0.dev2.tar.gz
  • Upload date:
  • Size: 110.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for mp4_py-2026.2.0.dev2.tar.gz
Algorithm Hash digest
SHA256 0e0c795f7d4e254236560a11e1292aa7621879da2b056144b9a6b8029b171699
MD5 16bbd8d8858adce367ae679fe60661c7
BLAKE2b-256 9477900a6b639429765b6a4d8c0816f12a761c5a5f59a0eaed4d2ec8c73a7a54

See more details on using hashes here.

Provenance

The following attestation bundles were made for mp4_py-2026.2.0.dev2.tar.gz:

Publisher: wheel.yml on shiguredo/mp4-py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file mp4_py-2026.2.0.dev2-cp314-cp314t-win_amd64.whl.

File metadata

File hashes

Hashes for mp4_py-2026.2.0.dev2-cp314-cp314t-win_amd64.whl
Algorithm Hash digest
SHA256 01118923ff3c661f2bd3555ff4482dfe6648ca44dbf0e7801e88258ad415c441
MD5 1f56159db651baee8e03f337df8cabb4
BLAKE2b-256 394fdef5d08f665b3ea25a648d0ffef9772845cd64af1d2e5e943581b7a06861

See more details on using hashes here.

Provenance

The following attestation bundles were made for mp4_py-2026.2.0.dev2-cp314-cp314t-win_amd64.whl:

Publisher: wheel.yml on shiguredo/mp4-py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file mp4_py-2026.2.0.dev2-cp314-cp314t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for mp4_py-2026.2.0.dev2-cp314-cp314t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 20d946983212acd8cabc7a4fb00c2514863cd6e6853cb20026c99541e4d3e7f3
MD5 8b45c356f67c04fb7cff532f5a534955
BLAKE2b-256 c5a32acef34e4755a405e3425580a59a57167d1045f26dc639228fba5ac30e23

See more details on using hashes here.

Provenance

The following attestation bundles were made for mp4_py-2026.2.0.dev2-cp314-cp314t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: wheel.yml on shiguredo/mp4-py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file mp4_py-2026.2.0.dev2-cp314-cp314t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for mp4_py-2026.2.0.dev2-cp314-cp314t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 b23e9a30a49a47c52a2467858918076662a8b6ad694efd3e697ffd026a36bbeb
MD5 36482d6de6b38e5da1ffbb52560c6443
BLAKE2b-256 becba0a048d4d25d859ccba8ffe78b78a63bcf09c6a6abc20a50253319552652

See more details on using hashes here.

Provenance

The following attestation bundles were made for mp4_py-2026.2.0.dev2-cp314-cp314t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: wheel.yml on shiguredo/mp4-py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file mp4_py-2026.2.0.dev2-cp314-cp314t-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for mp4_py-2026.2.0.dev2-cp314-cp314t-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 150d22add6b5dd291692a8394a63cca495a39e64bafb05afc7973e54cc3bfa90
MD5 4fac9200da6b3c374228003b921b37dd
BLAKE2b-256 4423e3f1c07bca29edb05e6f8e8b31d2e5924c0b3252ab885c7ea133cafc2ffe

See more details on using hashes here.

Provenance

The following attestation bundles were made for mp4_py-2026.2.0.dev2-cp314-cp314t-macosx_11_0_arm64.whl:

Publisher: wheel.yml on shiguredo/mp4-py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file mp4_py-2026.2.0.dev2-cp312-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for mp4_py-2026.2.0.dev2-cp312-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 0af597f5e18a855229b1956a35359c64a3f77e293859cfe9c79023a85d07134d
MD5 403a3215208579b13371229c02f66d14
BLAKE2b-256 ba594ca0bd7d268bc0cdfa848644619c6f28e9214a52bc99de15df5725c09733

See more details on using hashes here.

Provenance

The following attestation bundles were made for mp4_py-2026.2.0.dev2-cp312-abi3-win_amd64.whl:

Publisher: wheel.yml on shiguredo/mp4-py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file mp4_py-2026.2.0.dev2-cp312-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for mp4_py-2026.2.0.dev2-cp312-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 e9ca286b3d9cd8e5a5c115801b2935e31fde47aa76b7d0f644f3d140af478a6f
MD5 df09621d95f9de80ae102390ddaec499
BLAKE2b-256 cf4c80b95adc6435eb390b520e6864534d6bfaec80dc22d0465676e1db525fb1

See more details on using hashes here.

Provenance

The following attestation bundles were made for mp4_py-2026.2.0.dev2-cp312-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: wheel.yml on shiguredo/mp4-py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file mp4_py-2026.2.0.dev2-cp312-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for mp4_py-2026.2.0.dev2-cp312-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 e4e89c65c040add751dd004ff639326c53244e34e56caf65162bc00a478e85f9
MD5 4162460f2408c4ff5fbeddeaf97ef3f1
BLAKE2b-256 0ebcce917cdad5939af18a899141dde1dafba135a2bd890c777d5774df30b784

See more details on using hashes here.

Provenance

The following attestation bundles were made for mp4_py-2026.2.0.dev2-cp312-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: wheel.yml on shiguredo/mp4-py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file mp4_py-2026.2.0.dev2-cp312-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for mp4_py-2026.2.0.dev2-cp312-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 1753f8021abe6b3f72be87565941a7b0f35e34e9dd0bfd8759c204a160c870c1
MD5 874b6253caade311a41e8d6a9a61ab92
BLAKE2b-256 8c7cb5cfd7a2fa4fe18d044e434e00f1c33f9af647c5bdc925123e7d3e9c4f31

See more details on using hashes here.

Provenance

The following attestation bundles were made for mp4_py-2026.2.0.dev2-cp312-abi3-macosx_11_0_arm64.whl:

Publisher: wheel.yml on shiguredo/mp4-py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page