この記事のねらい
「torchcodec」という名前を最近よく見かけるようになったけど、いったい何なの？という方向けに、このライブラリの正体と、なぜ今知っておくべきなのかを解説します。
対象読者
- PyTorchで動画や音声を扱ったことがある人
- torchaudioやtorchvisionを使っている人
- 「nightly版」と聞いてピンとくる人
- これからマルチメディアAIに手を出そうとしている人
ゴール
- torchcodecが何であるかを理解する
- なぜ今、PyTorchエコシステム全体にとって重要なのかを把握する
- PyTorch nightly版との関係性を理解する
- 将来の移行に備えられるようになる
TL;DR
torchcodecは、PyTorchエコシステムにおける動画・音声デコード/エンコードの「次世代標準ライブラリ」です。torchaudioとtorchvisionのメディア処理機能を一本化する目的で開発されており、2025年現在、急速に移行が進んでいます。
そもそもtorchcodecとは？
torchcodecは、PyTorchの公式ブログで次のように紹介されています:
"We are pleased to officially announce torchcodec, a library for decoding videos into PyTorch tensors. It is fast, accurate, and easy to use. When running PyTorch models on videos, torchcodec is our recommended way to turn those videos into data your model can use."
（出典: PyTorch公式ブログ）
日本語に訳すと:
「torchcodecを正式に発表できることを嬉しく思います。これは動画をPyTorchテンソルにデコードするためのライブラリで、高速かつ正確で使いやすいです。動画に対してPyTorchモデルを実行する際、torchcodecはその動画をモデルが使えるデータに変換するための推奨方法です。」
つまり、動画ファイルを読み込んで、そのまま機械学習モデルに食わせられるテンソルに変換してくれる公式ツールです。
GitHub公式リポジトリの説明
"TorchCodec is a Python library for decoding video and audio data into PyTorch tensors, on CPU and CUDA GPU. It also supports audio encoding, and video encoding will come soon!"
（出典: meta-pytorch/torchcodec）
日本語訳:
「TorchCodecはCPUおよびCUDA GPU上で動画・音声データをPyTorchテンソルにデコードするPythonライブラリです。音声エンコードもサポートしており、動画エンコードも近日対応予定です！」
ポイントは以下:
- 動画と音声の両方に対応
- CPUだけでなくCUDA GPUでのデコードもサポート
- エンコード機能も追加中（音声は対応済み、動画は開発中）
なぜtorchcodecが「重要」なのか？
ここからが本題です。torchcodecは単なる「便利な新ライブラリ」ではありません。PyTorchエコシステム全体の再編に関わる、かなり重大なプロジェクトです。
torchaudioの衝撃的な発表
2025年4月、PyTorchチームは以下の発表を行いました:
"The decoding and encoding capabilities of TorchAudio for both audio and video data will migrate to TorchCodec, where we are consolidating all of PyTorch media decoding and encoding. TorchAudio's decoding and encoding APIs will be deprecated from TorchAudio 2.8, and they will be removed in TorchAudio 2.9, so we encourage users to migrate to TorchCodec as soon as possible."
（出典: GitHub Issue #3902）
日本語訳:
「TorchAudioの音声・動画データのデコード/エンコード機能はTorchCodecに移行します。PyTorchのメディアデコード/エンコードはここに集約されます。TorchAudioのデコード/エンコードAPIはTorchAudio 2.8から非推奨となり、2.9で削除されますので、できるだけ早くTorchCodecへの移行をお勧めします。」
これは結構インパクトのある話です。
公式ブログでもはっきり宣言
PyTorch公式ブログでも、この方針は明確に述べられています:
"In the long term, we want torchcodec to be the media decoding library for PyTorch. That means as we implement functionality in torchcodec, we will deprecate and eventually remove complementary features from torchaudio and torchvision."
日本語訳:
「長期的には、torchcodecをPyTorchのメディアデコードライブラリにしたいと考えています。つまり、torchcodecに機能を実装するにつれて、torchaudioとtorchvisionの補完的な機能は非推奨とし、最終的には削除します。」
つまり何が起きているのか？
これまでPyTorchで動画や音声を扱う場合、以下のように機能が分散していました:
| 機能 | 従来の担当 |
|---|---|
| 音声のデコード/エンコード | torchaudio |
| 動画のデコード | torchvision (video_reader) |
| 音声処理（変換、フィルタ等） | torchaudio |
これが torchcodec + torchaudio（処理特化）という構成に再編されます:
| 機能 | 新しい担当 |
|---|---|
| 音声・動画のデコード/エンコード | torchcodec |
| 音声処理（変換、モデル、データセット） | torchaudio（メンテナンスフェーズ移行） |
PyTorch nightly版との関係
さて、タイトルにもある「nightly版との関係」について説明します。
バージョン互換性テーブル
torchcodecとPyTorchのバージョンには厳密な対応関係があります:
| torchcodec | torch | Python |
|---|---|---|
| main / nightly | main / nightly | >=3.10, <=3.13 |
| 0.8 | 2.9 | >=3.10, <=3.13 |
| 0.7 | 2.8 | >=3.9, <=3.13 |
| 0.6 | 2.8 | >=3.9, <=3.13 |
（出典: GitHub README）
nightly版を使う意味
ポイントは一番上の行です。torchcodecの最新開発版（main/nightly）は、PyTorchのnightly版と対応しています。
これが意味するのは:
- torchcodecの最新機能をいち早く試したい場合、PyTorchもnightly版にする必要がある
- 安定版のPyTorchを使っている場合は、対応するtorchcodecのバージョンを使う
- 新機能（新しいベータCUDAバックエンド、Windowsサポートなど）はまずnightlyに入る
よくあるエラー
バージョンの不一致は、以下のようなエラーを引き起こします:
RuntimeError: Could not load libtorchcodec.
Likely causes:
1. FFmpeg is not properly installed in your environment.
2. The PyTorch version (2.9.0+cu126) is not compatible with
this version of TorchCodec.
このエラーが出たら、まず互換性テーブルを確認しましょう。
torchcodecの特徴と使い方
直感的なAPI
torchcodecの設計思想の一つは「使いやすさ」です:
from torchcodec.decoders import VideoDecoder
from torch import Tensor
decoder = VideoDecoder("my_video.mp4")
# インデックスベースのフレーム取得
first_ten_frames: Tensor = decoder[:10]
last_ten_frames: Tensor = decoder[-10:]
# 複数フレームの取得（インデックス/時間指定）
frames = decoder.get_frames_at(indices=[10, 0, 15])
frames = decoder.get_frames_played_at(seconds=[0.2, 3, 4.5])
動画ファイルをPythonのシーケンスのように扱えます。Pythonに慣れた人なら直感的に理解できる設計ですね。
サンプリングAPI
ML訓練パイプラインでよく使われる「クリップサンプリング」も簡単:
from torchcodec.samplers import clips_at_regular_timestamps
clips = clips_at_regular_timestamps(
decoder,
seconds_between_clip_starts=10, # 10秒ごとにクリップ開始
num_frames_per_clip=5, # 各クリップ5フレーム
seconds_between_frames=0.2, # フレーム間0.2秒
)
パフォーマンス
PyTorch公式ベンチマークによると:
"Torchcodec is consistently the best-performing library for the primary use case we designed it for: decoding many videos at once as a part of a training data loading pipeline. In particular, high-resolution videos see great gains with CUDA where decoding and transforms both happen on the GPU."
日本語訳:
「torchcodecは、設計された主要ユースケース（訓練データローディングパイプラインの一部として多数の動画を一度にデコードする）において、一貫して最高性能のライブラリです。特に高解像度動画では、デコードと変換の両方がGPUで行われるCUDAで大きな性能向上が見られます。」
特にCUDA対応のGPUデコードは、大量の動画を処理する訓練パイプラインで威力を発揮します。
インストール方法
CPU版（基本）
# PyTorchをインストール（公式インストラクションに従う）
pip install torch
# FFmpegをインストール（まだない場合）
conda install "ffmpeg" # または conda install "ffmpeg" -c conda-forge
# torchcodecをインストール
pip install torchcodec
CUDA版（GPU対応）
# CUDA対応のPyTorchをインストール
pip install torch --index-url https://download.pytorch.org/whl/cu126
# FFmpeg（NVDEC対応）をインストール
conda install "ffmpeg" -c conda-forge
# CUDA版torchcodecをインストール
pip install torchcodec --index-url=https://download.pytorch.org/whl/cu126
Windows（ベータサポート）
torchcodec 0.7からWindowsもベータサポートされています:
# CPU版
pip install torchcodec
# GPU版（conda-forge経由）
conda install torchcodec -c conda-forge
FFmpegの対応バージョン
torchcodecはFFmpeg 4, 5, 6, 7, 8に対応しています。システムにFFmpegがインストールされていれば、そのバージョンを使用します。
torchaudioからの移行
torchaudioを使っている方向けに、移行パスを説明します。
現状（2025年11月時点）
torchaudio 2.9では、load()とsave()が内部的にtorchcodecを使うようになっています:
"For convenience, load() and save() are now aliases to load_with_torchcodec() and save_with_torchcodec() respectively, which call the appropriate functions from TorchCodec."
（出典: torchaudio 2.9.0 documentation）
つまり、torchaudio 2.9を使っていれば、裏でtorchcodecが動いている状態です。
推奨される移行方法
公式は、直接torchcodecのAPIを使うことを推奨しています:
# 従来のtorchaudio
import torchaudio
waveform, sample_rate = torchaudio.load("audio.wav")
# torchcodec直接使用（推奨）
from torchcodec.decoders import AudioDecoder
decoder = AudioDecoder("audio.wav")
# AudioDecoderのAPIを使用
まだ移行しなくていい機能
torchaudioの以下の機能は引き続き維持されます:
- transforms（変換処理）
- functional（関数群）
- models（モデル）
- datasets（データセット）
- pipelines（パイプライン）
削除されるのは主にデコード/エンコード関連のAPIです。
よくあるトラブルと対処法
1. libtorchcodecが読み込めない
RuntimeError: Could not load libtorchcodec.
対処法:
- FFmpegが正しくインストールされているか確認
- PyTorchとtorchcodecのバージョン互換性を確認
- CUDAを使う場合は、libnvcuvid.soがあるか確認
2. CUDA GPUで動かない
対処法:
-
torch.cuda.is_available()がTrueか確認 -
ffmpeg -decoders | grep -i nvidiaでNVDECサポートを確認 - CUDA版のtorchcodecをインストールしたか確認
3. 特定のフォーマットが読めない
torchcodecはFFmpegのコーデックに依存しているため、FFmpegが対応していればtorchcodecでも読めます。
# FFmpegの対応コーデック確認
ffmpeg -codecs
まとめ
今すぐ知っておくべきこと
-
torchcodecはPyTorchのメディア処理の未来
- torchaudioとtorchvisionのデコード/エンコード機能を一本化
-
移行は進行中
- torchaudio 2.8から非推奨化が始まり、2.9で多くの機能が削除済み
- 今後新規プロジェクトではtorchcodecを使うべき
-
nightly版との関係
- 最新機能はnightly版で利用可能
- 安定版を使う場合は互換性テーブルを確認
-
インストールは簡単
- pip/condaで一発インストール可能
- FFmpegが必要だが、多くの環境で既にインストール済み
今後の展望
公式によると、以下の機能が予定されています:
- 動画エンコードのサポート（近日対応）
- パフォーマンスのさらなる改善
- より多くのプラットフォームへの対応強化
PyTorchでマルチメディアAIをやるなら、torchcodecは避けて通れない存在になりつつあります。今のうちに慣れておいて損はないでしょう。