2026-07-24 nightly release (93195e5)

Author: pytorchbot

.github/workflows/linux_cuda_wheel.yaml

@@ -196,6 +196,65 @@ jobs:
         run: |
           pytest --override-ini="addopts=-v" test --tb=short
 
+  install-and-test-no-ffmpeg:
+    # Asserts that the CUDA wheel works WITHOUT FFmpeg installed: it must import,
+    # the FFmpeg-free image decoders must work, and the FFmpeg-backed entry
+    # points must fail with a clear error.
+    runs-on: ubuntu-latest
+    needs: build
+    env:
+      PYTHON_VERSION: '3.10'
+      CUDA_VERSION: '12.6'
+    steps:
+      - name: Setup env vars
+        run: |
+          cuda_version_without_periods=$(echo "${{ env.CUDA_VERSION }}" | sed 's/\.//g')
+          echo cuda_version_without_periods=${cuda_version_without_periods} >> $GITHUB_ENV
+          python_version_without_periods=$(echo "${{ env.PYTHON_VERSION }}" | sed 's/\.//g')
+          echo python_version_without_periods=${python_version_without_periods} >> $GITHUB_ENV
+
+      - name: Check out repo
+        uses: actions/checkout@v6
+
+      - name: Remove src/ folder
+        run: bash packaging/remove_src.sh
+
+      - name: Setup conda env
+        uses: conda-incubator/setup-miniconda@v3
+        with:
+          auto-update-conda: true
+          miniforge-version: latest
+          activate-environment: test
+          python-version: ${{ env.PYTHON_VERSION }}
+
+      - name: Update pip
+        run: python -m pip install --upgrade pip
+
+      - name: Install PyTorch
+        run: bash packaging/install_pytorch.sh cu${{ env.cuda_version_without_periods }} "torch torchvision"
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: meta-pytorch_torchcodec__${{ env.PYTHON_VERSION }}_cu${{ env.cuda_version_without_periods }}_x86_64
+          path: dist/
+
+      - name: Install torchcodec from the wheel
+        run: bash packaging/install_torchcodec_wheel.sh "*cu${{ env.cuda_version_without_periods }}-cp${{ env.python_version_without_periods }}*.whl"
+
+      - name: Install test dependencies
+        run: bash packaging/install_test_dependencies.sh
+
+      - name: Assert FFmpeg is absent and torchcodec still imports
+        run: |
+          source packaging/helpers.sh
+          assert_ffmpeg_not_installed
+          python -c "import torchcodec; from torchcodec._core import ops; assert not ops._FFMPEG_AVAILABLE, 'FFmpeg was unexpectedly loaded'; print('OK: torchcodec imported without FFmpeg')"
+
+      - name: Run FFmpeg-free Python tests
+        run: |
+          FAIL_WITHOUT_JPEG=1 FAIL_WITHOUT_PNG=1 FAIL_WITHOUT_WEBP=1 FAIL_WITHOUT_AVIF=1 \
+            pytest --override-ini="addopts=-v" test/test_ffmpeg_optional.py test/test_decoders.py::TestImageDecoder
+
   build-docs:
     runs-on: linux.g5.4xlarge.nvidia.gpu
     env:

.github/workflows/linux_wheel.yaml

@@ -109,6 +109,60 @@ jobs:
         run: |
           FAIL_WITHOUT_JPEG=1 FAIL_WITHOUT_PNG=1 FAIL_WITHOUT_WEBP=1 FAIL_WITHOUT_AVIF=1 pytest --override-ini="addopts=-v" test
 
+  install-and-test-no-ffmpeg:
+    # Asserts that torchcodec works WITHOUT FFmpeg installed: the package must
+    # import, the FFmpeg-free image decoders must work, and the FFmpeg-backed
+    # entry points must fail with a clear error.
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.10']
+    needs: build
+    steps:
+      - name: Check out repo
+        uses: actions/checkout@v6
+
+      - name: Remove src/ folder
+        run: bash packaging/remove_src.sh
+
+      - name: Setup conda env
+        uses: conda-incubator/setup-miniconda@v3
+        with:
+          auto-update-conda: true
+          miniforge-version: latest
+          activate-environment: test
+          python-version: ${{ matrix.python-version }}
+
+      - name: Update pip
+        run: python -m pip install --upgrade pip
+
+      - name: Install PyTorch
+        run: bash packaging/install_pytorch.sh cpu "torch torchvision"
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: meta-pytorch_torchcodec__${{ matrix.python-version }}_cpu_x86_64
+          path: dist/
+
+      - name: Install torchcodec from the wheel
+        run: bash packaging/install_torchcodec_wheel.sh
+
+      - name: Install test dependencies
+        run: bash packaging/install_test_dependencies.sh
+
+      # Deliberately NO "Install ffmpeg" step here.
+      - name: Assert FFmpeg is absent and torchcodec still imports
+        run: |
+          source packaging/helpers.sh
+          assert_ffmpeg_not_installed
+          python -c "import torchcodec; from torchcodec._core import ops; assert not ops._FFMPEG_AVAILABLE, 'FFmpeg was unexpectedly loaded'; print('OK: torchcodec imported without FFmpeg')"
+
+      - name: Run FFmpeg-free Python tests
+        run: |
+          FAIL_WITHOUT_JPEG=1 FAIL_WITHOUT_PNG=1 FAIL_WITHOUT_WEBP=1 FAIL_WITHOUT_AVIF=1 \
+            pytest --override-ini="addopts=-v" test/test_ffmpeg_optional.py test/test_decoders.py::TestImageDecoder
+
   install-and-test-third-party-interface:
     runs-on: ubuntu-latest
     strategy:

README.md

@@ -11,11 +11,13 @@ videos and audio, or run inference, TorchCodec is how you turn these into data.
 We achieve these capabilities through:
 
 * Pythonic APIs that mirror Python and PyTorch conventions.
-* Relying on [FFmpeg](https://www.ffmpeg.org/) to do the decoding and encoding.
-  TorchCodec uses the version of FFmpeg you already have installed. FFmpeg is a
-  mature library with broad coverage available on most systems. It is, however,
-  not easy to use. TorchCodec abstracts FFmpeg's complexity to ensure it is used
-  correctly and efficiently.
+* Relying on [FFmpeg](https://www.ffmpeg.org/) to do the video and audio
+  decoding and encoding. TorchCodec uses the version of FFmpeg you already have
+  installed. FFmpeg is a mature library with broad coverage available on most
+  systems. It is, however, not easy to use. TorchCodec abstracts FFmpeg's
+  complexity to ensure it is used correctly and efficiently. (FFmpeg is
+  optional, and the image decoders don't need it: see [Installing
+  TorchCodec](#installing-torchcodec).)
 * Returning data as PyTorch tensors, ready to be fed into PyTorch transforms
   or used directly to train models.
 
@@ -105,6 +107,13 @@ with encoder.open_file("output.mp4"):
    conda install "ffmpeg" -c conda-forge
    ```
 
+   > **Note:** FFmpeg is an *optional* dependency. It is needed for video
+   > and audio decoding and encoding (`VideoDecoder`, `AudioDecoder`,
+   > `VideoEncoder`, `AudioEncoder`, etc.). The image decoders
+   > (`decode_image`, `decode_jpeg`, `decode_png`, etc.)
+   > do **not** require FFmpeg, so if you only need image decoding you can skip
+   > this step.
+
 2. Install PyTorch and TorchCodec:
 
    ```bash

src/torchcodec/_core/DecodeAvif.cpp

@@ -17,8 +17,9 @@
 namespace facebook::torchcodec {
 
 torch::stable::Tensor decode_avif(
-    [[maybe_unused]] const torch::stable::Tensor& data,
-    [[maybe_unused]] int64_t mode) {
+    [[maybe_unused]] const torch::stable::Tensor& input,
+    [[maybe_unused]] int64_t mode,
+    [[maybe_unused]] int64_t output_dtype) {
   STD_TORCH_CHECK(
       false,
       "decode_avif: torchcodec was not compiled with libavif support. "
@@ -88,14 +89,20 @@ ExifOrientation avif_exif_orientation(const avifImage* image) {
 
 torch::stable::Tensor decode_avif(
     const torch::stable::Tensor& input,
-    int64_t mode) {
+    int64_t mode,
+    int64_t output_dtype,
+    int64_t num_threads) {
   // Based on
   // https://github.com/AOMediaCodec/libavif/blob/main/examples/avif_example_decode_memory.c
   validate_encoded_data(input);
+  STD_TORCH_CHECK(
+      num_threads >= 1, "num_threads must be >= 1, got ", num_threads);
 
   DecoderPtr decoder(avifDecoderCreate());
   STD_TORCH_CHECK(decoder != nullptr, "Failed to create avif decoder.");
 
+  decoder->maxThreads = static_cast<int>(num_threads);
+
   auto result = avifDecoderSetIOMemory(
       decoder.get(), input.const_data_ptr<uint8_t>(), input.numel());
   STD_TORCH_CHECK(
@@ -124,6 +131,9 @@ torch::stable::Tensor decode_avif(
       static_cast<bool>(decoder->alphaPresent));
   int num_channels = return_rgb ? 3 : 4;
 
+  bool output_16 = should_output_uint16(
+      static_cast<OutputDtype>(output_dtype), decoder->image->depth > 8);
+
   torch::stable::Tensor output;
   uint8_t* output_ptr = nullptr;
   int64_t frame_num_bytes = 0;
@@ -141,8 +151,7 @@ torch::stable::Tensor decode_avif(
     std::memset(&rgb, 0, sizeof(rgb));
     avifRGBImageSetDefaults(&rgb, decoder->image);
 
-    // TODO_IMAGE: support 10 and 12 bits.
-    rgb.depth = 8;
+    rgb.depth = output_16 ? 16 : 8;
     rgb.format = return_rgb ? AVIF_RGB_FORMAT_RGB : AVIF_RGB_FORMAT_RGBA;
     rgb.ignoreAlpha = return_rgb ? AVIF_TRUE : AVIF_FALSE;
 
@@ -152,14 +161,14 @@ torch::stable::Tensor decode_avif(
            num_channels,
            static_cast<int64_t>(rgb.height),
            static_cast<int64_t>(rgb.width)},
-          kStableUInt8,
+          output_16 ? kStableUInt16 : kStableUInt8,
           std::nullopt,
           std::nullopt,
           std::nullopt,
           torch::headeronly::MemoryFormat::ChannelsLast);
-      output_ptr = output.mutable_data_ptr<uint8_t>();
-      frame_num_bytes =
-          static_cast<int64_t>(num_channels) * rgb.height * rgb.width;
+      output_ptr = static_cast<uint8_t*>(output.mutable_data_ptr());
+      frame_num_bytes = static_cast<int64_t>(num_channels) * rgb.height *
+          rgb.width * (output_16 ? 2 : 1);
     }
 
     rgb.pixels = output_ptr + i * frame_num_bytes;

src/torchcodec/_core/DecodeAvif.h

@@ -11,7 +11,9 @@
 namespace facebook::torchcodec {
 
 FORCE_PUBLIC_VISIBILITY torch::stable::Tensor decode_avif(
-    const torch::stable::Tensor& data,
-    int64_t mode);
+    const torch::stable::Tensor& input,
+    int64_t mode,
+    int64_t output_dtype,
+    int64_t num_threads);
 
 } // namespace facebook::torchcodec

src/torchcodec/_core/DecodeGif.h

@@ -17,7 +17,7 @@ namespace facebook::torchcodec {
 // RGB_ALPHA produces a 4-channel RGBA tensor preserving transparency as alpha;
 // UNCHANGED produces RGBA if the GIF has any transparency, else RGB.
 FORCE_PUBLIC_VISIBILITY torch::stable::Tensor decode_gif(
-    const torch::stable::Tensor& data,
+    const torch::stable::Tensor& input,
     int64_t mode);
 
 } // namespace facebook::torchcodec

src/torchcodec/_core/DecodeJpeg.cpp

@@ -17,7 +17,7 @@
 namespace facebook::torchcodec {
 
 torch::stable::Tensor decode_jpeg(
-    [[maybe_unused]] const torch::stable::Tensor& data,
+    [[maybe_unused]] const torch::stable::Tensor& input,
     [[maybe_unused]] int64_t mode) {
   STD_TORCH_CHECK(
       false,
@@ -300,6 +300,8 @@ void decode_rows(
     }
     output_ptr += stride;
   }
+
+  jpeg_finish_decompress(&jpeg_ctx);
 }
 
 } // namespace
@@ -417,9 +419,6 @@ void decode_rows(
 //
 /* clang-format on */
 
-// TODO_IMAGE: align names. everywhere. this is input, other places it's data,
-// other places it's something else. Should align here, in the header, in the
-// custom op definition, etc. Across codecs.
 torch::stable::Tensor decode_jpeg(
     const torch::stable::Tensor& input,
     int64_t mode) {
@@ -440,6 +439,10 @@ torch::stable::Tensor decode_jpeg(
       input.numel(),
       static_cast<ImageReadMode>(mode));
 
+  // Note: this must be called before jpeg_finish_decompress(), otherwise we get
+  // garbage exif data.
+  ExifOrientation exif_orientation = fetch_jpeg_exif_orientation(&jpeg_ctx);
+
   // We want output to be channels last
   int64_t stride =
       static_cast<int64_t>(jpeg_ctx.output_width) * num_output_channels;
@@ -469,11 +472,16 @@ torch::stable::Tensor decode_jpeg(
 
   decode_rows(jpeg_ctx, error_ctx, output_ptr, stride, cmyk_helper);
 
-  // EXIF markers were parsed during jpeg_read_header so this is just an
-  // in-memory lookup (i.e. we're not going back to the beginning of the file)
-  ExifOrientation exif_orientation = fetch_jpeg_exif_orientation(&jpeg_ctx);
+  // Flip raw CMYK samples so our output matches PIL.
+  if (static_cast<ImageReadMode>(mode) == ImageReadMode::UNCHANGED &&
+      (jpeg_ctx.jpeg_color_space == JCS_CMYK ||
+       jpeg_ctx.jpeg_color_space == JCS_YCCK)) {
+    int64_t num_bytes = output.numel();
+    for (int64_t i = 0; i < num_bytes; ++i) {
+      output_ptr[i] = static_cast<uint8_t>(255 - output_ptr[i]);
+    }
+  }
 
-  jpeg_finish_decompress(&jpeg_ctx);
   jpeg_destroy_decompress(&jpeg_ctx);
   return exif_orientation_transform(
       stable_permute(output, {2, 0, 1}), exif_orientation);

src/torchcodec/_core/DecodeJpeg.h

@@ -11,7 +11,7 @@
 namespace facebook::torchcodec {
 
 FORCE_PUBLIC_VISIBILITY torch::stable::Tensor decode_jpeg(
-    const torch::stable::Tensor& data,
+    const torch::stable::Tensor& input,
     int64_t mode);
 
 } // namespace facebook::torchcodec