Fix video pipeline alpha outputs

Author: nadermx

AGENTS.md

@@ -0,0 +1,33 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+- `backgroundremover/` contains the core library, CLI/server entry points, and U2Net implementation.
+- `background_remover_gui.py` and `run_gui.bat` provide the desktop GUI launcher.
+- `models/` holds bundled model artifacts; downloaded weights live under `~/.u2net/` at runtime.
+- `examplefiles/` provides sample inputs; `dist/` and `archive/` are build outputs.
+
+## Build, Test, and Development Commands
+- `pip install -r requirements.txt` installs runtime dependencies for local development.
+- `pip install -e .` installs the package in editable mode with console scripts.
+- `python -m backgroundremover.cmd.cli -i "input.jpg" -o "output.png"` runs the CLI locally.
+- `backgroundremover -i "input.jpg" -o "output.png"` uses the installed console script.
+- `backgroundremover-server -p 5000` starts the HTTP server (Flask + Waitress).
+- `python background_remover_gui.py` launches the GUI.
+- `docker build -t bgremover .` builds the Docker image described in `Dockerfile`.
+
+## Coding Style & Naming Conventions
+- Follow standard Python style (PEP 8) with 4-space indentation.
+- Use `snake_case` for modules/functions and `CapWords` for classes.
+- Keep CLI flags consistent with existing short/long options in `backgroundremover/cmd/cli.py`.
+
+## Testing Guidelines
+- No automated test suite is currently present.
+- When adding new behavior, include a short manual check in the PR (command + expected output), or add tests if you introduce test tooling.
+
+## Commit & Pull Request Guidelines
+- Commit messages in history are short, imperative sentences (e.g., `Improve CLI validation and error handling`).
+- PRs should include a concise summary, reproduction or usage commands, and sample outputs (images or logs) when changing model behavior or CLI flags.
+
+## Runtime Assets & Configuration
+- Models download to `~/.u2net/` on first use; document any new model names or file paths.
+- Video processing depends on `ffmpeg`; note shared memory settings when using Docker.

README.md

@@ -288,7 +288,16 @@ backgroundremover -i "/path/to/video.mp4" -mk -o "output.matte.mp4"
 
 ### Video Playback and Compatibility
 
-**Important:** The transparent `.mov` files created by this tool use the `qtrle` (QuickTime RLE) codec with alpha channel. Not all video players support this format correctly.
+**Important:** Transparent `.mov` outputs default to the lossless `qtrle` (QuickTime RLE) codec with alpha channel. This is large but preserves transparency. You can switch codecs with `--alpha-codec` for smaller or more compatible outputs.
+
+Examples:
+```bash
+# macOS-friendly ProRes 4444 (still large, but more compatible)
+backgroundremover -i "video.mp4" -tv --alpha-codec prores_ks -o "output.mov"
+
+# Smaller WebM with alpha (if your tools support it)
+backgroundremover -i "video.mp4" -tv --alpha-codec libvpx-vp9 -o "output.webm"
+```
 
 **Recommended video players:**
 - **mpv** (https://mpv.io) - Best support for transparent videos (Linux, Mac, Windows)
@@ -318,7 +327,6 @@ backgroundremover -i "/path/to/video.mp4" -mk -o "output.matte.mp4"
    ```
 
 ### Advance usage for video
-
 Change the framerate of the video (default is set to 30)
 
 ```bash

backgroundremover/cmd/cli.py

@@ -128,6 +128,18 @@ def main():
         type=lambda x: bool(strtobool(x)),
         help="Output transparent video format mov",
     )
+    ap.add_argument(
+        "--alpha-codec",
+        default="auto",
+        type=str,
+        help="Codec for transparent video output (auto, prores_ks, qtrle, libvpx-vp9). Auto defaults to lossless qtrle.",
+    )
+    ap.add_argument(
+        "--alpha-pix-fmt",
+        default=None,
+        type=str,
+        help="Override pixel format for transparent video output (e.g., yuva444p10le).",
+    )
 
     ap.add_argument(
         "-tov",
@@ -282,23 +294,29 @@ def is_image_file(filename):
                                                gpu_batchsize=args.gpubatchsize,
                                                model_name=args.model,
                                                frame_limit=args.framelimit,
-                                               framerate=args.framerate)
+                                               framerate=args.framerate,
+                                               alpha_codec=args.alpha_codec,
+                                               alpha_pix_fmt=args.alpha_pix_fmt)
                 elif args.transparentvideoovervideo:
                     utilities.transparentvideoovervideo(output_path, os.path.abspath(args.backgroundvideo.name),
                                                         input_path,
                                                         worker_nodes=args.workernodes,
                                                         gpu_batchsize=args.gpubatchsize,
                                                         model_name=args.model,
                                                         frame_limit=args.framelimit,
-                                                        framerate=args.framerate)
+                                                        framerate=args.framerate,
+                                                        alpha_codec=args.alpha_codec,
+                                                        alpha_pix_fmt=args.alpha_pix_fmt)
                 elif args.transparentvideooverimage:
                     utilities.transparentvideooverimage(output_path, os.path.abspath(args.backgroundimage.name),
                                                         input_path,
                                                         worker_nodes=args.workernodes,
                                                         gpu_batchsize=args.gpubatchsize,
                                                         model_name=args.model,
                                                         frame_limit=args.framelimit,
-                                                        framerate=args.framerate)
+                                                        framerate=args.framerate,
+                                                        alpha_codec=args.alpha_codec,
+                                                        alpha_pix_fmt=args.alpha_pix_fmt)
                 elif args.transparentgif:
                     utilities.transparentgif(output_path, input_path,
                                              worker_nodes=args.workernodes,
@@ -373,23 +391,29 @@ def is_image_file(filename):
                                        gpu_batchsize=args.gpubatchsize,
                                        model_name=args.model,
                                        frame_limit=args.framelimit,
-                                       framerate=args.framerate)
+                                       framerate=args.framerate,
+                                       alpha_codec=args.alpha_codec,
+                                       alpha_pix_fmt=args.alpha_pix_fmt)
         elif args.transparentvideoovervideo:
             utilities.transparentvideoovervideo(os.path.abspath(args.output.name), os.path.abspath(args.backgroundvideo.name),
                                                 os.path.abspath(args.input.name),
                                                 worker_nodes=args.workernodes,
                                                 gpu_batchsize=args.gpubatchsize,
                                                 model_name=args.model,
                                                 frame_limit=args.framelimit,
-                                                framerate=args.framerate)
+                                                framerate=args.framerate,
+                                                alpha_codec=args.alpha_codec,
+                                                alpha_pix_fmt=args.alpha_pix_fmt)
         elif args.transparentvideooverimage:
             utilities.transparentvideooverimage(os.path.abspath(args.output.name), os.path.abspath(args.backgroundimage.name),
                                                 os.path.abspath(args.input.name),
                                                 worker_nodes=args.workernodes,
                                                 gpu_batchsize=args.gpubatchsize,
                                                 model_name=args.model,
                                                 frame_limit=args.framelimit,
-                                                framerate=args.framerate)
+                                                framerate=args.framerate,
+                                                alpha_codec=args.alpha_codec,
+                                                alpha_pix_fmt=args.alpha_pix_fmt)
         elif args.transparentgif:
             utilities.transparentgif(os.path.abspath(args.output.name), os.path.abspath(args.input.name),
                                      worker_nodes=args.workernodes,

backgroundremover/utilities.py

@@ -1,5 +1,6 @@
 import os
 import math
+from fractions import Fraction
 import torch.multiprocessing as multiprocessing
 import subprocess as sp
 import time
@@ -14,6 +15,43 @@
 multiprocessing.set_start_method('spawn', force=True)
 
 
+def _parse_frame_rate(rate_str):
+    try:
+        return float(Fraction(rate_str))
+    except Exception:
+        return float(rate_str)
+
+
+def _alpha_encoding_args(output, alpha_codec, alpha_pix_fmt):
+    ext = Path(output).suffix.lower()
+    if alpha_codec in (None, "auto"):
+        if ext == ".webm":
+            alpha_codec = "libvpx-vp9"
+        else:
+            alpha_codec = "qtrle"
+
+    if alpha_codec == "prores_ks":
+        args = ["-c:v", "prores_ks", "-profile:v", "4"]
+        pix_fmt = alpha_pix_fmt or "yuva444p10le"
+        args += ["-pix_fmt", pix_fmt]
+        return args
+
+    if alpha_codec == "libvpx-vp9":
+        args = ["-c:v", "libvpx-vp9", "-crf", "30", "-b:v", "0"]
+        pix_fmt = alpha_pix_fmt or "yuva420p"
+        args += ["-pix_fmt", pix_fmt]
+        return args
+
+    if alpha_codec == "qtrle":
+        pix_fmt = alpha_pix_fmt or "argb"
+        return ["-c:v", "qtrle", "-pix_fmt", pix_fmt]
+
+    args = ["-c:v", alpha_codec]
+    if alpha_pix_fmt:
+        args += ["-pix_fmt", alpha_pix_fmt]
+    return args
+
+
 def worker(worker_nodes,
            worker_index,
            result_dict,
@@ -104,9 +142,13 @@ def matte_key(output, file_path,
 
     if framerate == -1:
         print(F"FRAME RATE DETECTED: {frame_rate_str} (if this looks wrong, override the frame rate)")
-        framerate = math.ceil(eval(frame_rate_str))
+        framerate_str = frame_rate_str
+        framerate_value = _parse_frame_rate(frame_rate_str)
+    else:
+        framerate_str = str(framerate)
+        framerate_value = float(framerate)
 
-    print(F"FRAME RATE: {framerate} TOTAL FRAMES: {total_frames}")
+    print(F"FRAME RATE: {framerate_value} TOTAL FRAMES: {total_frames}")
 
     p = multiprocessing.Process(target=capture_frames,
                                 args=(file_path, frames_dict, gpu_batchsize * prefetched_batches, total_frames))
@@ -163,7 +205,7 @@ def matte_key(output, file_path,
                                '-vcodec', 'rawvideo',
                                '-s', F"{frame.shape[1]}x320",
                                '-pix_fmt', 'gray',
-                               '-r', F"{framerate}",
+                               '-r', framerate_str,
                                '-i', '-',
                                '-an',
                                '-vcodec', 'mpeg4',
@@ -260,7 +302,9 @@ def transparentvideo(output, file_path,
                      model_name,
                      frame_limit=-1,
                      prefetched_batches=4,
-                     framerate=-1):
+                     framerate=-1,
+                     alpha_codec="auto",
+                     alpha_pix_fmt=None):
     temp_dir = tempfile.TemporaryDirectory()
     tmpdirname = Path(temp_dir.name)
     temp_file = os.path.abspath(os.path.join(tmpdirname, "matte.mp4"))
@@ -272,10 +316,13 @@ def transparentvideo(output, file_path,
               prefetched_batches,
               framerate)
     print("Starting alphamerge")
+    encoding_args = _alpha_encoding_args(output, alpha_codec, alpha_pix_fmt)
     cmd = [
         'ffmpeg', '-y', '-i', file_path, '-i', temp_file, '-filter_complex',
-        '[1][0]scale2ref[mask][main];[main][mask]alphamerge', '-c:v', 'qtrle', '-shortest', output
+        '[1][0]scale2ref[mask][main];[main][mask]alphamerge[v]',
+        '-map', '[v]', '-map', '0:a?', '-shortest'
     ]
+    cmd += encoding_args + [output]
 
     sp.run(cmd)
     print("Process finished")
@@ -292,7 +339,9 @@ def transparentvideoovervideo(output, overlay, file_path,
                          model_name,
                          frame_limit=-1,
                          prefetched_batches=4,
-                         framerate=-1):
+                         framerate=-1,
+                         alpha_codec="auto",
+                         alpha_pix_fmt=None):
     temp_dir = tempfile.TemporaryDirectory()
     tmpdirname = Path(temp_dir.name)
     temp_file = os.path.abspath(os.path.join(tmpdirname, "matte.mp4"))
@@ -304,10 +353,13 @@ def transparentvideoovervideo(output, overlay, file_path,
               prefetched_batches,
               framerate)
     print("Starting alphamerge")
+    encoding_args = _alpha_encoding_args(output, alpha_codec, alpha_pix_fmt)
     cmd = [
         'ffmpeg', '-y', '-i', file_path, '-i', temp_file, '-i', overlay, '-filter_complex',
-        '[1][0]scale2ref[mask][main];[main][mask]alphamerge[vid];[vid][2:v]scale2ref[fg][bg];[bg][fg]overlay[out]', '-map', '[out]', '-shortest', output
+        '[1][0]scale2ref[mask][main];[main][mask]alphamerge[vid];[vid][2:v]scale2ref[fg][bg];[bg][fg]overlay[out]',
+        '-map', '[out]', '-map', '2:a?', '-shortest'
     ]
+    cmd += encoding_args + [output]
     sp.run(cmd)
     print("Process finished")
     try:
@@ -323,7 +375,9 @@ def transparentvideooverimage(output, overlay, file_path,
                          model_name,
                          frame_limit=-1,
                          prefetched_batches=4,
-                         framerate=-1):
+                         framerate=-1,
+                         alpha_codec="auto",
+                         alpha_pix_fmt=None):
     temp_dir = tempfile.TemporaryDirectory()
     tmpdirname = Path(temp_dir.name)
     temp_file = os.path.abspath(os.path.join(tmpdirname, "matte.mp4"))
@@ -342,11 +396,13 @@ def transparentvideooverimage(output, overlay, file_path,
     ]
     sp.run(cmd)
     print("Starting alphamerge")
+    encoding_args = _alpha_encoding_args(output, alpha_codec, alpha_pix_fmt)
     cmd = [
         'ffmpeg', '-y', '-i', temp_image, '-i', file_path, '-i', temp_file, '-filter_complex',
-        '[0:v]scale2ref=oh*mdar:ih[bg];[1:v]scale2ref=oh*mdar:ih[fg];[bg][fg]overlay=(W-w)/2:(H-h)/2:shortest=1[out]',
-        '-map', '[out]', '-shortest', output
+        '[2][1]scale2ref[mask][main];[main][mask]alphamerge[fg];[0:v]scale2ref[bg][fg];[bg][fg]overlay=(W-w)/2:(H-h)/2:shortest=1[out]',
+        '-map', '[out]', '-map', '1:a?', '-shortest'
     ]
+    cmd += encoding_args + [output]
     sp.run(cmd)
     print("Process finished")
     try: