[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-nadermx--backgroundremover":3,"tool-nadermx--backgroundremover":62},[4,18,26,36,46,54],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":17},4358,"openclaw","openclaw\u002Fopenclaw","OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。\n\n这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。\n\nOpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你",349277,3,"2026-04-06T06:32:30",[13,14,15,16],"Agent","开发框架","图像","数据工具","ready",{"id":19,"name":20,"github_repo":21,"description_zh":22,"stars":23,"difficulty_score":10,"last_commit_at":24,"category_tags":25,"status":17},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,"2026-04-05T11:01:52",[14,15,13],{"id":27,"name":28,"github_repo":29,"description_zh":30,"stars":31,"difficulty_score":32,"last_commit_at":33,"category_tags":34,"status":17},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",158594,2,"2026-04-16T23:34:05",[14,13,35],"语言模型",{"id":37,"name":38,"github_repo":39,"description_zh":40,"stars":41,"difficulty_score":42,"last_commit_at":43,"category_tags":44,"status":17},8272,"opencode","anomalyco\u002Fopencode","OpenCode 是一款开源的 AI 编程助手（Coding Agent），旨在像一位智能搭档一样融入您的开发流程。它不仅仅是一个代码补全插件，而是一个能够理解项目上下文、自主规划任务并执行复杂编码操作的智能体。无论是生成全新功能、重构现有代码，还是排查难以定位的 Bug，OpenCode 都能通过自然语言交互高效完成，显著减少开发者在重复性劳动和上下文切换上的时间消耗。\n\n这款工具专为软件开发者、工程师及技术研究人员设计，特别适合希望利用大模型能力来提升编码效率、加速原型开发或处理遗留代码维护的专业人群。其核心亮点在于完全开源的架构，这意味着用户可以审查代码逻辑、自定义行为策略，甚至私有化部署以保障数据安全，彻底打破了传统闭源 AI 助手的“黑盒”限制。\n\n在技术体验上，OpenCode 提供了灵活的终端界面（Terminal UI）和正在测试中的桌面应用程序，支持 macOS、Windows 及 Linux 全平台。它兼容多种包管理工具，安装便捷，并能无缝集成到现有的开发环境中。无论您是追求极致控制权的资深极客，还是渴望提升产出的独立开发者，OpenCode 都提供了一个透明、可信",144296,1,"2026-04-16T14:50:03",[13,45],"插件",{"id":47,"name":48,"github_repo":49,"description_zh":50,"stars":51,"difficulty_score":32,"last_commit_at":52,"category_tags":53,"status":17},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",108322,"2026-04-10T11:39:34",[14,15,13],{"id":55,"name":56,"github_repo":57,"description_zh":58,"stars":59,"difficulty_score":32,"last_commit_at":60,"category_tags":61,"status":17},6121,"gemini-cli","google-gemini\u002Fgemini-cli","gemini-cli 是一款由谷歌推出的开源 AI 命令行工具，它将强大的 Gemini 大模型能力直接集成到用户的终端环境中。对于习惯在命令行工作的开发者而言，它提供了一条从输入提示词到获取模型响应的最短路径，无需切换窗口即可享受智能辅助。\n\n这款工具主要解决了开发过程中频繁上下文切换的痛点，让用户能在熟悉的终端界面内直接完成代码理解、生成、调试以及自动化运维任务。无论是查询大型代码库、根据草图生成应用，还是执行复杂的 Git 操作，gemini-cli 都能通过自然语言指令高效处理。\n\n它特别适合广大软件工程师、DevOps 人员及技术研究人员使用。其核心亮点包括支持高达 100 万 token 的超长上下文窗口，具备出色的逻辑推理能力；内置 Google 搜索、文件操作及 Shell 命令执行等实用工具；更独特的是，它支持 MCP（模型上下文协议），允许用户灵活扩展自定义集成，连接如图像生成等外部能力。此外，个人谷歌账号即可享受免费的额度支持，且项目基于 Apache 2.0 协议完全开源，是提升终端工作效率的理想助手。",100752,"2026-04-10T01:20:03",[45,13,15,14],{"id":63,"github_repo":64,"name":65,"description_en":66,"description_zh":67,"ai_summary_zh":67,"readme_en":68,"readme_zh":69,"quickstart_zh":70,"use_case_zh":71,"hero_image_url":72,"owner_login":73,"owner_name":74,"owner_avatar_url":75,"owner_bio":76,"owner_company":76,"owner_location":76,"owner_email":76,"owner_twitter":76,"owner_website":77,"owner_url":78,"languages":79,"stars":92,"forks":93,"last_commit_at":94,"license":95,"difficulty_score":10,"env_os":96,"env_gpu":97,"env_ram":98,"env_deps":99,"category_tags":108,"github_topics":110,"view_count":32,"oss_zip_url":76,"oss_zip_packed_at":76,"status":17,"created_at":123,"updated_at":124,"faqs":125,"releases":155},8293,"nadermx\u002Fbackgroundremover","backgroundremover","Background Remover lets you Remove Background from images and video using AI with a simple command line interface that is free and open source.","backgroundremover 是一款免费开源的命令行工具，利用先进的人工智能技术，帮助用户轻松从图片或视频中移除背景。它有效解决了传统抠图流程繁琐、专业软件昂贵以及处理视频帧效率低下的痛点，让用户只需输入简单指令即可快速获得透明背景的素材。\n\n这款工具特别适合开发者集成到自动化工作流中，也深受设计师、视频创作者及技术爱好者的欢迎。对于熟悉终端操作的普通用户，它同样提供了高效便捷的本地处理方案，无需依赖云端服务即可保护数据隐私。\n\n其核心技术亮点在于内置了高精度的 U2Net 模型，能够智能识别主体并保留复杂边缘细节。更值得一提的是，backgroundremover 不仅支持静态图片，还具备强大的视频处理能力，能自动利用 GPU 加速，将处理速度提升 5 到 10 倍。此外，项目提供了完善的 Docker 支持，极大简化了环境配置过程，确保在不同系统上都能稳定运行，是实现高质量批量抠图的理想选择。","# BackgroundRemover\n![Background Remover](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fnadermx_backgroundremover_readme_4f28b6dc1c0a.png)\n\u003Cimg alt=\"background remover video\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fnadermx_backgroundremover_readme_6c0cfe77a04d.gif\" height=\"200\" \u002F>\u003Cbr>\nBackgroundRemover is a command line tool to remove background from [image](https:\u002F\u002Fgithub.com\u002Fnadermx\u002Fbackgroundremover#image) and [video](https:\u002F\u002Fgithub.com\u002Fnadermx\u002Fbackgroundremover#video) using AI, made by [nadermx](https:\u002F\u002Fjohn.nader.mx) to power [https:\u002F\u002FBackgroundRemoverAI.com](https:\u002F\u002Fbackgroundremoverai.com). If you wonder why it was made read this [short blog post](https:\u002F\u002Fjohnathannader.com\u002Fmy-first-open-source-project\u002F).\u003Cbr>\n\n\n### Requirements\n\n* python >= 3.6\n* python3.6-dev #or what ever version of python you use\n* torch and torchvision stable version (https:\u002F\u002Fpytorch.org)\n* ffmpeg 4.4+\n\n* To clarify, you must install both python and whatever dev version of python you installed. IE; python3.10-dev with python3.10 or python3.8-dev with python3.8\n\n#### How to install torch and ffmpeg\n\nGo to https:\u002F\u002Fpytorch.org and scroll down to `INSTALL PYTORCH` section and follow the instructions.\n\n**For CPU-only (default):**\n\n```bash\npip3 install torch torchvision --index-url https:\u002F\u002Fdownload.pytorch.org\u002Fwhl\u002Fcpu\n```\n\n**For GPU (CUDA) support:**\n\n```bash\n# For CUDA 11.8\npip3 install torch torchvision --index-url https:\u002F\u002Fdownload.pytorch.org\u002Fwhl\u002Fcu118\n\n# For CUDA 12.1\npip3 install torch torchvision --index-url https:\u002F\u002Fdownload.pytorch.org\u002Fwhl\u002Fcu121\n```\n\nVisit https:\u002F\u002Fpytorch.org\u002Fget-started\u002Flocally\u002F to find the correct command for your CUDA version.\n\n**To install ffmpeg and python-dev:**\n\n```bash\nsudo apt install ffmpeg python3.6-dev\n```\n\n### Installation\nTo Install backgroundremover, install it from pypi\n\n```bash\npip install --upgrade pip\npip install backgroundremover\n```\nPlease note that when you first run the program, it will check to see if you have the u2net models, if you do not, it will pull them from this repo\n\nIt is also possible to run this without installing it via pip, just clone the git to local start a virtual env and install requirements and run\n```bash\npython -m backgroundremover.cmd.cli -i \"video.mp4\" -mk -o \"output.mov\"\n```\nand for windows\n```bash\npython.exe -m backgroundremover.cmd.cli -i \"video.mp4\" -mk -o \"output.mov\"\n```\n### Installation using Docker\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fnadermx\u002Fbackgroundremover.git\ncd backgroundremover\ndocker build -t bgremover .\n# Basic usage (models will be downloaded on each run)\nalias backgroundremover='docker run -it --rm -v \"$(pwd):\u002Ftmp\" bgremover:latest'\n\n# Recommended: Persist models between runs to avoid re-downloading\nmkdir -p ~\u002F.u2net\nalias backgroundremover='docker run -it --rm -v \"$(pwd):\u002Ftmp\" -v \"$HOME\u002F.u2net:\u002Froot\u002F.u2net\" bgremover:latest'\n\n# For video processing: Increase shared memory to avoid multiprocessing errors\nalias backgroundremover='docker run -it --rm --shm-size=2g -v \"$(pwd):\u002Ftmp\" -v \"$HOME\u002F.u2net:\u002Froot\u002F.u2net\" bgremover:latest'\n```\n\n**Note for Docker video processing:** Video processing uses multiprocessing which requires adequate shared memory. If you encounter errors like `OSError: [Errno 95] Operation not supported`, use `--shm-size=2g` (or higher) or `--ipc=host` when running the container.\n\n### GPU Acceleration\n\nBackgroundRemover automatically detects and uses your GPU if available, which provides significant speed improvements (typically 5-10x faster than CPU).\n\n**To verify GPU is being used:**\n\n```bash\npython3 -c \"import torch; print('GPU available:', torch.cuda.is_available()); print('GPU name:', torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'N\u002FA')\"\n```\n\n**Troubleshooting GPU issues:**\n\n1. **GPU not detected**: Ensure you installed the CUDA-compatible version of PyTorch (see installation instructions above)\n2. **Out of memory errors**: Reduce GPU batch size with `-gb 1` flag\n3. **Slow performance on CPU**: Install CUDA-compatible PyTorch for GPU acceleration\n4. **CUDA version mismatch**: Match your PyTorch CUDA version with your system's CUDA installation\n\nThe tool will automatically fall back to CPU if GPU is not available or encounters errors.\n\n### Usage as a cli\n## Image\n\nRemove the background from a local file image\n\n```bash\nbackgroundremover -i \"\u002Fpath\u002Fto\u002Fimage.jpeg\" -o \"output.png\"\n```\n\nSupported image formats: `.jpg`, `.jpeg`, `.png`, `.heic`, `.heif` (HEIC\u002FHEIF support requires pillow-heif)\n### Process all images in a folder\n\nYou can now remove backgrounds from all supported image or video files in a folder using the `--input-folder` (`-if`) option. You can also optionally set an output folder using `--output-folder` (`-of`). If `--output-folder` is not provided, the outputs will be saved in the same input folder, prefixed with `output_`.\n\n### Example: Folder of Images\n\n```bash\nbackgroundremover -if \"\u002Fpath\u002Fto\u002Fimage-folder\" -of \"\u002Fpath\u002Fto\u002Foutput-folder\"\n```\n\nThis will process all `.jpg`, `.jpeg`, `.png`, `.heic`, and `.heif` images in the folder and save the results to the output folder.\n\n\n\n### Advance usage for image background removal\n\n**Alpha Matting for Better Edge Quality:**\n\nBy default, backgroundremover produces soft, natural edges. For some use cases (like cartoons, graphics, or sharp-edged objects), you may want sharper edges or better edge refinement.\n\n```bash\n# Enable alpha matting for refined edges\nbackgroundremover -i \"\u002Fpath\u002Fto\u002Fimage.jpeg\" -a -o \"output.png\"\n\n# Adjust erosion size for sharper\u002Fsofter edges (default: 10)\n# Smaller values (1-5) = sharper, harder edges (good for cartoons\u002Fgraphics)\n# Larger values (15-25) = softer, more natural edges (good for portraits)\nbackgroundremover -i \"\u002Fpath\u002Fto\u002Fimage.jpeg\" -a -ae 5 -o \"output.png\"\n```\n\n**Alpha matting parameters:**\n- `-a` - Enable alpha matting\n- `-af` - Foreground threshold (default: 240)\n- `-ab` - Background threshold (default: 10)\n- `-ae` - Erosion size (1-25, default: 10) - controls edge sharpness\n- `-az` - Base size (default: 1000) - affects processing resolution\n\n**Change the model for different subjects:**\n\n```bash\n# For humans\u002Fpeople - most accurate for human subjects\nbackgroundremover -i \"\u002Fpath\u002Fto\u002Fimage.jpeg\" -m \"u2net_human_seg\" -o \"output.png\"\n\n# For general objects - good all-around model (default)\nbackgroundremover -i \"\u002Fpath\u002Fto\u002Fimage.jpeg\" -m \"u2net\" -o \"output.png\"\n\n# Faster processing - lower accuracy but quicker\nbackgroundremover -i \"\u002Fpath\u002Fto\u002Fimage.jpeg\" -m \"u2netp\" -o \"output.png\"\n```\n\n### Output only the mask (binary mask\u002Fmatte)\n\n```bash\nbackgroundremover -i \"\u002Fpath\u002Fto\u002Fimage.jpeg\" -om -o \"mask.png\"\n```\n\n### Replace background with a custom color\n\n```bash\n# Replace with red background\nbackgroundremover -i \"\u002Fpath\u002Fto\u002Fimage.jpeg\" -bc \"255,0,0\" -o \"output.png\"\n\n# Replace with green background\nbackgroundremover -i \"\u002Fpath\u002Fto\u002Fimage.jpeg\" -bc \"0,255,0\" -o \"output.png\"\n\n# Replace with blue background\nbackgroundremover -i \"\u002Fpath\u002Fto\u002Fimage.jpeg\" -bc \"0,0,255\" -o \"output.png\"\n```\n\n### Replace background with a custom image\n\n```bash\n# Replace background with another image\nbackgroundremover -i \"\u002Fpath\u002Fto\u002Fimage.jpeg\" -bi \"\u002Fpath\u002Fto\u002Fbackground.jpg\" -o \"output.png\"\n```\n\n### Use with pipes (stdin\u002Fstdout)\n\nYou can use backgroundremover in Unix pipelines by reading from stdin and writing to stdout:\n\n```bash\n# Read from stdin, write to stdout\ncat input.jpg | backgroundremover > output.png\n\n# Use with other tools in a pipeline\ncurl https:\u002F\u002Fexample.com\u002Fimage.jpg | backgroundremover | convert - -resize 50% smaller.png\n\n# Equivalent explicit syntax\nbackgroundremover -i - -o - \u003C input.jpg > output.png\n```\n\nNote: Pipe mode assumes image input (not video).\n\n### Run as HTTP API Server\n\nYou can run backgroundremover as an HTTP API server:\n\n```bash\n# Start server on default port 5000\nbackgroundremover-server\n\n# Specify custom host and port\nbackgroundremover-server --addr 0.0.0.0 --port 8080\n```\n\nAPI Usage:\n\n```bash\n# Upload image via POST\ncurl -X POST -F \"file=@image.jpg\" http:\u002F\u002Flocalhost:5000\u002F -o output.png\n\n# Process from URL via GET\ncurl \"http:\u002F\u002Flocalhost:5000\u002F?url=https:\u002F\u002Fexample.com\u002Fimage.jpg\" -o output.png\n\n# With alpha matting\ncurl \"http:\u002F\u002Flocalhost:5000\u002F?url=https:\u002F\u002Fexample.com\u002Fimage.jpg&a=true&af=240\" -o output.png\n\n# Choose model\ncurl \"http:\u002F\u002Flocalhost:5000\u002F?url=https:\u002F\u002Fexample.com\u002Fimage.jpg&model=u2net_human_seg\" -o output.png\n```\n\nParameters:\n- `a` - Enable alpha matting\n- `af` - Alpha matting foreground threshold (default: 240)\n- `ab` - Alpha matting background threshold (default: 10)\n- `ae` - Alpha matting erosion size (default: 10)\n- `az` - Alpha matting base size (default: 1000)\n- `model` - Model choice: `u2net`, `u2netp`, or `u2net_human_seg`\n\n## Video\n\n### remove background from video and make transparent mov\n\n```bash\nbackgroundremover -i \"\u002Fpath\u002Fto\u002Fvideo.mp4\" -tv -o \"output.mov\"\n```\n### Process all videos in a folder\n\nYou can now remove backgrounds from all supported image or video files in a folder using the `--input-folder` (`-if`) option. You can also optionally set an output folder using `--output-folder` (`-of`). If `--output-folder` is not provided, the outputs will be saved in the same input folder, prefixed with `output_`.\n\n### Example: Folder of Videos to Transparent `.mov`\n\n```bash\nbackgroundremover -if \"\u002Fpath\u002Fto\u002Fvideo-folder\" -of \"\u002Fpath\u002Fto\u002Foutput-folder\" -tv\n```\n\nYou can also combine additional options:\n\n```bash\nbackgroundremover -if \"videos\" -of \"processed\" -m \"u2net_human_seg\" -fr 30 -tv\n```\n\n- Uses the `u2net_human_seg` model\n- Overrides video framerate to 30 fps\n- Outputs transparent `.mov` files into the `processed\u002F` folder\n- Supported video formats: `.mp4`, `.mov`, `.webm`, `.ogg`, `.gif`\n- Output files will be named like `output_filename.ext` in the output folder\n\n### remove background from local video and overlay it over other video\n```bash\nbackgroundremover -i \"\u002Fpath\u002Fto\u002Fvideo.mp4\" -tov -bv \"\u002Fpath\u002Fto\u002Fbackground_video.mp4\" -o \"output.mov\"\n```\n### remove background from local video and overlay it over an image\n```bash\nbackgroundremover -i \"\u002Fpath\u002Fto\u002Fvideo.mp4\" -toi -bi \"\u002Fpath\u002Fto\u002Fbackground_image.png\" -o \"output.mov\"\n```\n\n### remove background from video and make transparent gif\n\n\n```bash\nbackgroundremover -i \"\u002Fpath\u002Fto\u002Fvideo.mp4\" -tg -o \"output.gif\"\n```\n### Make matte key file (green screen overlay)\n\nMake a matte file for premiere\n\n```bash\nbackgroundremover -i \"\u002Fpath\u002Fto\u002Fvideo.mp4\" -mk -o \"output.matte.mp4\"\n```\n\n### Video Playback and Compatibility\n\n**Important:** Transparent `.mov` outputs default to ProRes 4444 (`prores_ks` with `yuva444p10le`) which provides 10-bit color with alpha channel and excellent compatibility with professional video editors (DaVinci Resolve, Premiere, Final Cut Pro). You can switch codecs with `--alpha-codec` if needed.\n\nExamples:\n```bash\n# Smaller WebM with alpha (if your tools support it)\nbackgroundremover -i \"video.mp4\" -tv --alpha-codec libvpx-vp9 -o \"output.webm\"\n\n# Legacy qtrle codec (lossless but very large files)\nbackgroundremover -i \"video.mp4\" -tv --alpha-codec qtrle -o \"output.mov\"\n```\n\n**Recommended video players:**\n- **mpv** (https:\u002F\u002Fmpv.io) - Best support for transparent videos (Linux, Mac, Windows)\n- **QuickTime Player** (Mac) - Native support on macOS\n- **DaVinci Resolve** \u002F **Adobe Premiere** - Full support in video editors (may need to enable alpha channel in properties)\n\n**Common issues:**\n- **VLC**: May not display transparency correctly - shows distorted colors or green\u002Fpurple tint\n- **Windows Media Player**: Limited transparency support\n- **Web browsers**: Limited support for ProRes codec\n\n**Workarounds if your player doesn't support transparency:**\n\n1. **Convert to WebM with VP9 (better compatibility):**\n   ```bash\n   ffmpeg -i output.mov -c:v libvpx-vp9 -pix_fmt yuva420p output.webm\n   ```\n\n2. **Add a colored background (for testing):**\n   ```bash\n   ffmpeg -f lavfi -i color=white:s=1920x1080 -i output.mov -filter_complex 'overlay=0:0' -c:v libx264 output_with_bg.mp4\n   ```\n\n3. **Use the transparent GIF output instead** (simpler but lower quality):\n   ```bash\n   backgroundremover -i \"video.mp4\" -tg -o \"output.gif\"\n   ```\n\n### Advance usage for video\n\nChange the framerate of the video (default is set to 30)\n\n```bash\nbackgroundremover -i \"\u002Fpath\u002Fto\u002Fvideo.mp4\" -fr 30 -tv -o \"output.mov\"\n```\n\nSet total number of frames of the video (default is set to -1, ie the remove background from full video)\n\n```bash\nbackgroundremover -i \"\u002Fpath\u002Fto\u002Fvideo.mp4\" -fl 150 -tv -o \"output.mov\"\n```\n\nChange the gpu batch size of the video (default is set to 1)\n\n```bash\nbackgroundremover -i \"\u002Fpath\u002Fto\u002Fvideo.mp4\" -gb 4 -tv -o \"output.mov\"\n```\n\nChange the number of workers working on video (default is set to 1)\n\n```bash\nbackgroundremover -i \"\u002Fpath\u002Fto\u002Fvideo.mp4\" -wn 4 -tv -o \"output.mov\"\n```\n\n**Note:** Using high worker counts (>4) may cause `ConnectionResetError` or crashes on some systems due to multiprocessing limitations. If you experience errors, reduce the number of workers or use `-wn 1`. The optimal number depends on your CPU cores and available RAM.\nchange the model for different background removal methods between `u2netp`, `u2net`, or `u2net_human_seg` and limit the frames to 150\n```bash\nbackgroundremover -i \"\u002Fpath\u002Fto\u002Fvideo.mp4\" -m \"u2net_human_seg\" -fl 150 -tv -o \"output.mov\"\n```\n\n## As a library\n### Remove background image\n\n```python\nfrom backgroundremover.bg import remove\n\ndef remove_bg(src_img_path, out_img_path):\n    model_choices = [\"u2net\", \"u2net_human_seg\", \"u2netp\"]\n    f = open(src_img_path, \"rb\")\n    data = f.read()\n    img = remove(data, model_name=model_choices[0],\n                 alpha_matting=True,\n                 alpha_matting_foreground_threshold=240,\n                 alpha_matting_background_threshold=10,\n                 alpha_matting_erode_structure_size=10,\n                 alpha_matting_base_size=1000)\n    f.close()\n    f = open(out_img_path, \"wb\")\n    f.write(img)\n    f.close()\n```\n\n### Generate only a binary mask\n\n```python\nfrom backgroundremover.bg import remove\n\nf = open(\"input.jpg\", \"rb\")\ndata = f.read()\nmask = remove(data, model_name=\"u2net\", only_mask=True)\nf.close()\n\nf = open(\"mask.png\", \"wb\")\nf.write(mask)\nf.close()\n```\n\n### Replace background with custom color\n\n```python\nfrom backgroundremover.bg import remove\n\nf = open(\"input.jpg\", \"rb\")\ndata = f.read()\n# Use RGB tuple for background color (255, 0, 0) = red\nimg = remove(data, model_name=\"u2net\", background_color=(255, 0, 0))\nf.close()\n\nf = open(\"output.png\", \"wb\")\nf.write(img)\nf.close()\n```\n\n### Replace background with custom image\n\n```python\nfrom backgroundremover.bg import remove\n\n# Read input image\nwith open(\"input.jpg\", \"rb\") as f:\n    input_data = f.read()\n\n# Read background image\nwith open(\"background.jpg\", \"rb\") as f:\n    bg_data = f.read()\n\n# Remove background and composite over background image\nresult = remove(input_data, model_name=\"u2net\", background_image=bg_data)\n\n# Save result\nwith open(\"output.png\", \"wb\") as f:\n    f.write(result)\n```\n\n## Troubleshooting\n\n### \"EOFError: Ran out of input\" or Model Loading Errors\n\nIf you see errors like `EOFError: Ran out of input` or model loading failures:\n\n**Cause:** The model file download was corrupted or interrupted.\n\n**Solution:**\n```bash\n# Delete the corrupted model file\nrm ~\u002F.u2net\u002Fu2net.pth\n# Or for other models:\nrm ~\u002F.u2net\u002Fu2netp.pth\nrm ~\u002F.u2net\u002Fu2net_human_seg.pth\n\n# Then run backgroundremover again - it will re-download the model\nbackgroundremover -i \"your-image.jpg\" -o \"output.png\"\n```\n\n**Prevention:** The tool now automatically validates and retries failed downloads, but if you have an old corrupted model from a previous version, you'll need to delete it manually.\n\n### Background Not Removed or Parts Missing\n\nIf the background is not being removed properly, or parts of your subject are disappearing:\n\n1. **Try a different model:**\n   - Use `u2net_human_seg` for people\u002Fportraits\n   - Use `u2net` (default) for general objects\n   - The model choice significantly affects results\n\n2. **Adjust alpha matting:**\n   - Enable with `-a` flag for better edge detection\n   - Adjust threshold values `-af` and `-ab` if parts are incorrectly classified\n\n3. **Check your input:**\n   - Ensure good lighting and contrast between subject and background\n   - Avoid backgrounds that are similar in color to your subject\n   - Consider manually cropping to include more recognizable background\n\n### Transparency Issues or Strange Colors\n\nIf the output video shows distorted colors, green\u002Fpurple tint, or transparency isn't working:\n\n1. **Check your video player** - See the \"Video Playback and Compatibility\" section above\n2. **Use a recommended player** like mpv or QuickTime Player\n3. **Convert to a different format** if needed (see WebM conversion examples)\n\n### Large Output File Sizes\n\nThe transparent `.mov` files use ProRes 4444 codec and will be larger than the input. ProRes 4444 provides much better compression than the previous qtrle codec while maintaining 10-bit color with alpha:\n\n- File sizes are significantly smaller than qtrle but still larger than standard video\n- This is expected for high-quality transparency preservation\n- Use `--alpha-codec libvpx-vp9` with `.webm` output for smaller files if your tools support it\n\n### Poor Quality or Inaccurate Results\n\nBackground removal quality depends on:\n\n1. **Input quality** - Higher resolution and better lighting improve results\n2. **Subject complexity** - Simple, well-defined subjects work best\n3. **Model limitations** - AI models may struggle with:\n   - Very similar colors between subject and background\n   - Complex hair\u002Ffur details\n   - Transparent or reflective objects\n   - Unusual subjects the model wasn't trained on\n\n**Tips for better results:**\n- Use `u2net_human_seg` specifically for human subjects\n- Enable alpha matting with `-a` for complex edges\n- Ensure good contrast between subject and background when capturing\n- Try different alpha matting parameters (`-ae`, `-af`, `-ab`)\n\n## Testing\n\nCurrently, this project does not have automated test cases. Testing is done manually using sample images and videos.\n\n### Manual Testing\n\nTo test backgroundremover functionality:\n\n**Test Image Background Removal:**\n```bash\n# Basic test\nbackgroundremover -i \"test_image.jpg\" -o \"output.png\"\n\n# Test with alpha matting\nbackgroundremover -i \"test_image.jpg\" -a -ae 15 -o \"output.png\"\n\n# Test mask generation\nbackgroundremover -i \"test_image.jpg\" -om -o \"mask.png\"\n\n# Test custom background color\nbackgroundremover -i \"test_image.jpg\" -bc \"0,255,0\" -o \"output.png\"\n```\n\n**Test Video Processing:**\n```bash\n# Test transparent video\nbackgroundremover -i \"test_video.mp4\" -tv -o \"output.mov\"\n\n# Test matte key\nbackgroundremover -i \"test_video.mp4\" -mk -o \"matte.mov\"\n\n# Test transparent GIF\nbackgroundremover -i \"test_video.mp4\" -tg -o \"output.gif\"\n```\n\n**Test HTTP Server:**\n```bash\n# Start server\nbackgroundremover-server --port 5000\n\n# Test with curl (in another terminal)\ncurl -X POST -F \"file=@test_image.jpg\" http:\u002F\u002Flocalhost:5000\u002F -o output.png\n```\n\n### Contributing Tests\n\nAutomated tests using pytest or unittest would be a valuable contribution to this project. Test cases should cover:\n- Image processing with different formats (JPG, PNG, HEIC)\n- Video processing with different codecs\n- CLI argument validation\n- HTTP API endpoints\n- Model loading and inference\n- Error handling\n\n## Todo\n\n### Completed\n- ✅ HTTP API server (use `backgroundremover-server`)\n- ✅ Comprehensive documentation and troubleshooting\n- ✅ Docker support with model persistence\n- ✅ HEIC\u002FHEIF image format support\n- ✅ Pipe support (stdin\u002Fstdout)\n- ✅ Custom background colors and images\n- ✅ Binary mask output\n- ✅ Folder batch processing\n\n### In Progress \u002F Future Features\n- Support for additional models (ISNet, BiRefNet, U2Net cloth segmentation)\n- CoreML support for Apple Silicon acceleration\n- Standalone executable (no Python installation required)\n- Automated test suite\n- Real-time background removal for video streaming\n- Convert logic from video to image to utilize more GPU on image removal\n- Ability to provide feedback on results to improve training datasets\n- Support for custom\u002Fuser-provided models\n- Google Colab notebook\n\nContributions welcome! See open issues for details.\n\n### Pull requests\n\nAccepted\n\n### If you like this library\n\nGive a link to our project [BackgroundRemoverAI.com](https:\u002F\u002Fbackgroundremoverai.com) or this git, telling people that you like it or use it.\n\n### Reason for project\n\nWe made it our own package after merging together parts of others, adding in a few features of our own via posting parts as bounty questions on superuser, etc.  As well as asked on hackernews earlier to open source the image part, so decided to add in video, and a bit more.\n\n\n\n### References\n\n- https:\u002F\u002Farxiv.org\u002Fpdf\u002F2005.09007.pdf\n- https:\u002F\u002Fgithub.com\u002FNathanUA\u002FU-2-Net\n- https:\u002F\u002Fgithub.com\u002Fpymatting\u002Fpymatting\n- https:\u002F\u002Fgithub.com\u002Fdanielgatis\u002Frembg\n- https:\u002F\u002Fgithub.com\u002Fecsplendid\u002Frembg-greenscreen\n- https:\u002F\u002Fsuperuser.com\u002Fquestions\u002F1647590\u002Fhave-ffmpeg-merge-a-matte-key-file-over-the-normal-video-file-removing-the-backg\n- https:\u002F\u002Fsuperuser.com\u002Fquestions\u002F1648680\u002Fffmpeg-alphamerge-two-videos-into-a-gif-with-transparent-background\u002F1649339?noredirect=1#comment2522687_1649339\n- https:\u002F\u002Fsuperuser.com\u002Fquestions\u002F1649817\u002Fffmpeg-overlay-a-video-after-alphamerging-two-others\u002F1649856#1649856\n\n### License\n\n- Copyright (c) 2021-present [Johnathan Nader](https:\u002F\u002Fgithub.com\u002Fnadermx)\n- Copyright (c) 2020-present [Lucas Nestler](https:\u002F\u002Fgithub.com\u002FClashLuke)\n- Copyright (c) 2020-present [Dr. Tim Scarfe](https:\u002F\u002Fgithub.com\u002Fecsplendid)\n- Copyright (c) 2020-present [Daniel Gatis](https:\u002F\u002Fgithub.com\u002Fdanielgatis)\n\nCode Licensed under [MIT License](.\u002FLICENSE.txt)\nModels Licensed under [Apache License 2.0](.\u002Fmodels\u002Flicense)\n","# 背景移除工具\n![背景移除工具](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fnadermx_backgroundremover_readme_4f28b6dc1c0a.png)\n\u003Cimg alt=\"背景移除视频\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fnadermx_backgroundremover_readme_6c0cfe77a04d.gif\" height=\"200\" \u002F>\u003Cbr>\nBackgroundRemover 是一款基于 AI 的命令行工具，可用于从 [图片](https:\u002F\u002Fgithub.com\u002Fnadermx\u002Fbackgroundremover#image) 和 [视频](https:\u002F\u002Fgithub.com\u002Fnadermx\u002Fbackgroundremover#video) 中移除背景。该工具由 [nadermx](https:\u002F\u002Fjohn.nader.mx) 开发，旨在为 [https:\u002F\u002FBackgroundRemoverAI.com](https:\u002F\u002Fbackgroundremoverai.com) 提供支持。如果您想知道为何开发此工具，请阅读这篇 [简短博客文章](https:\u002F\u002Fjohnathannader.com\u002Fmy-first-open-source-project\u002F)。\u003Cbr>\n\n\n### 需求\n\n* python >= 3.6\n* python3.6-dev # 或您使用的任何 Python 版本\n* 稳定版的 torch 和 torchvision (https:\u002F\u002Fpytorch.org)\n* ffmpeg 4.4+\n\n* 需要说明的是，您必须同时安装 Python 和您所安装的 Python 开发版本。例如：python3.10-dev 与 python3.10，或 python3.8-dev 与 python3.8。\n\n#### 如何安装 torch 和 ffmpeg\n\n访问 https:\u002F\u002Fpytorch.org，向下滚动至 `INSTALL PYTORCH` 部分，并按照说明操作。\n\n**仅使用 CPU（默认）：**\n\n```bash\npip3 install torch torchvision --index-url https:\u002F\u002Fdownload.pytorch.org\u002Fwhl\u002Fcpu\n```\n\n**支持 GPU（CUDA）：**\n\n```bash\n# 对于 CUDA 11.8\npip3 install torch torchvision --index-url https:\u002F\u002Fdownload.pytorch.org\u002Fwhl\u002Fcu118\n\n# 对于 CUDA 12.1\npip3 install torch torchvision --index-url https:\u002F\u002Fdownload.pytorch.org\u002Fwhl\u002Fcu121\n```\n\n请访问 https:\u002F\u002Fpytorch.org\u002Fget-started\u002Flocally\u002F 查找适合您 CUDA 版本的正确命令。\n\n**安装 ffmpeg 和 python-dev：**\n\n```bash\nsudo apt install ffmpeg python3.6-dev\n```\n\n### 安装\n要安装 backgroundremover，请从 pypi 安装：\n\n```bash\npip install --upgrade pip\npip install backgroundremover\n```\n请注意，首次运行程序时，它会检查您是否已安装 u2net 模型；如果未安装，它将从该仓库中下载这些模型。\n\n此外，您也可以不通过 pip 安装而直接运行该工具：只需克隆 git 仓库到本地，启动虚拟环境，安装依赖项并运行：\n```bash\npython -m backgroundremover.cmd.cli -i \"video.mp4\" -mk -o \"output.mov\"\n```\n对于 Windows 系统：\n```bash\npython.exe -m backgroundremover.cmd.cli -i \"video.mp4\" -mk -o \"output.mov\"\n```\n\n### 使用 Docker 安装\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fnadermx\u002Fbackgroundremover.git\ncd backgroundremover\ndocker build -t bgremover .\n# 基本用法（每次运行都会下载模型）\nalias backgroundremover='docker run -it --rm -v \"$(pwd):\u002Ftmp\" bgremover:latest'\n\n# 推荐：在多次运行之间保留模型，以避免重复下载\nmkdir -p ~\u002F.u2net\nalias backgroundremover='docker run -it --rm -v \"$(pwd):\u002Ftmp\" -v \"$HOME\u002F.u2net:\u002Froot\u002F.u2net\" bgremover:latest'\n\n# 处理视频时：增加共享内存以避免多进程错误\nalias backgroundremover='docker run -it --rm --shm-size=2g -v \"$(pwd):\u002Ftmp\" -v \"$HOME\u002F.u2net:\u002Froot\u002F.u2net\" bgremover:latest'\n```\n\n**Docker 视频处理注意事项：** 视频处理使用多进程，需要足够的共享内存。如果您遇到类似 `OSError: [Errno 95] Operation not supported` 的错误，请在运行容器时使用 `--shm-size=2g`（或更高）选项，或使用 `--ipc=host`。\n\n### GPU 加速\n\nBackgroundRemover 会自动检测并使用您的 GPU（如果可用），从而显著提升速度（通常比 CPU 快 5–10 倍）。\n\n**验证 GPU 是否正在使用：**\n\n```bash\npython3 -c \"import torch; print('GPU 可用:', torch.cuda.is_available()); print('GPU 名称:', torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'N\u002FA')\"\n```\n\n**GPU 问题排查：**\n\n1. **未检测到 GPU**：请确保您已安装兼容 CUDA 的 PyTorch 版本（参见上述安装说明）。\n2. **显存不足错误**：使用 `-gb 1` 标志降低 GPU 批量大小。\n3. **CPU 性能缓慢**：安装兼容 CUDA 的 PyTorch 以实现 GPU 加速。\n4. **CUDA 版本不匹配**：请确保您的 PyTorch CUDA 版本与系统中的 CUDA 安装版本一致。\n\n如果 GPU 不可用或出现错误，该工具将自动回退到 CPU。\n\n### 命令行使用\n## 图片\n\n移除本地文件图片的背景：\n\n```bash\nbackgroundremover -i \"\u002Fpath\u002Fto\u002Fimage.jpeg\" -o \"output.png\"\n```\n\n支持的图片格式：`.jpg`, `.jpeg`, `.png`, `.heic`, `.heif`（HEIC\u002FHEIF 支持需要 pillow-heif）。\n### 处理文件夹中的所有图片\n\n现在您可以使用 `--input-folder` (`-if`) 选项，一次性移除文件夹中所有支持的图片或视频文件的背景。您还可以选择性地使用 `--output-folder` (`-of`) 设置输出文件夹。如果未提供 `--output-folder`，输出文件将保存在输入文件夹中，并在文件名前加上 `output_` 前缀。\n\n### 示例：图片文件夹\n\n```bash\nbackgroundremover -if \"\u002Fpath\u002Fto\u002Fimage-folder\" -of \"\u002Fpath\u002Fto\u002Foutput-folder\"\n```\n\n这将处理文件夹中的所有 `.jpg`, `.jpeg`, `.png`, `.heic` 和 `.heif` 图片，并将结果保存到输出文件夹中。\n\n\n\n### 图片背景移除的高级用法\n\n**Alpha 蒙版以获得更好的边缘质量：**\n\n默认情况下，backgroundremover 会生成柔和自然的边缘。但在某些情况下（如卡通、图形或具有清晰边缘的对象），您可能希望获得更锐利的边缘或更好的边缘细化效果。\n\n```bash\n# 启用 alpha 蒙版以获得更精细的边缘\nbackgroundremover -i \"\u002Fpath\u002Fto\u002Fimage.jpeg\" -a -o \"output.png\"\n\n# 调整侵蚀大小以获得更锐利或更柔和的边缘（默认值：10）\n# 较小的值（1–5）= 更锐利、更硬朗的边缘（适用于卡通\u002F图形）\n# 较大的值（15–25）= 更柔和、更自然的边缘（适用于人像）\nbackgroundremover -i \"\u002Fpath\u002Fto\u002Fimage.jpeg\" -a -ae 5 -o \"output.png\"\n```\n\n**Alpha 蒙版参数：**\n- `-a` - 启用 alpha 蒙版\n- `-af` - 前景阈值（默认值：240）\n- `-ab` - 背景阈值（默认值：10）\n- `-ae` - 侵蚀大小（1–25，默认值：10）——控制边缘的锐度\n- `-az` - 基础尺寸（默认值：1000）——影响处理分辨率\n\n**针对不同主题更改模型：**\n\n```bash\n# 用于人类\u002F人物——对人类主题最准确\nbackgroundremover -i \"\u002Fpath\u002Fto\u002Fimage.jpeg\" -m \"u2net_human_seg\" -o \"output.png\"\n\n# 用于一般物体——通用且表现良好的模型（默认）\nbackgroundremover -i \"\u002Fpath\u002Fto\u002Fimage.jpeg\" -m \"u2net\" -o \"output.png\"\n\n# 更快的处理速度——准确性较低但速度更快\nbackgroundremover -i \"\u002Fpath\u002Fto\u002Fimage.jpeg\" -m \"u2netp\" -o \"output.png\"\n```\n\n### 仅输出掩码（二值掩码\u002F遮罩）\n\n```bash\nbackgroundremover -i \"\u002Fpath\u002Fto\u002Fimage.jpeg\" -om -o \"mask.png\"\n```\n\n### 将背景替换为自定义颜色\n\n```bash\n# 替换为红色背景\nbackgroundremover -i \"\u002Fpath\u002Fto\u002Fimage.jpeg\" -bc \"255,0,0\" -o \"output.png\"\n\n# 替换为绿色背景\nbackgroundremover -i \"\u002Fpath\u002Fto\u002Fimage.jpeg\" -bc \"0,255,0\" -o \"output.png\"\n\n# 替换为蓝色背景\nbackgroundremover -i \"\u002Fpath\u002Fto\u002Fimage.jpeg\" -bc \"0,0,255\" -o \"output.png\"\n```\n\n### 用自定义图片替换背景\n\n```bash\n# 用另一张图片替换背景\nbackgroundremover -i \"\u002Fpath\u002Fto\u002Fimage.jpeg\" -bi \"\u002Fpath\u002Fto\u002Fbackground.jpg\" -o \"output.png\"\n```\n\n### 与管道结合使用（stdin\u002Fstdout）\n\n您可以在 Unix 管道中使用 backgroundremover，通过从 stdin 读取并写入 stdout：\n\n```bash\n# 从 stdin 读取，写入 stdout\ncat input.jpg | backgroundremover > output.png\n\n# 在管道中与其他工具结合使用\ncurl https:\u002F\u002Fexample.com\u002Fimage.jpg | backgroundremover | convert - -resize 50% smaller.png\n\n# 等效的显式语法\nbackgroundremover -i - -o - \u003C input.jpg > output.png\n```\n\n注意：管道模式假定输入为图像（而非视频）。\n\n### 作为 HTTP API 服务器运行\n\n您可以将 backgroundremover 作为 HTTP API 服务器运行：\n\n```bash\n# 在默认端口 5000 上启动服务器\nbackgroundremover-server\n\n# 指定自定义主机和端口\nbackgroundremover-server --addr 0.0.0.0 --port 8080\n```\n\nAPI 使用方法：\n\n```bash\n# 通过 POST 上传图片\ncurl -X POST -F \"file=@image.jpg\" http:\u002F\u002Flocalhost:5000\u002F -o output.png\n\n# 通过 GET 从 URL 处理\ncurl \"http:\u002F\u002Flocalhost:5000\u002F?url=https:\u002F\u002Fexample.com\u002Fimage.jpg\" -o output.png\n\n# 带有 Alpha 蒙版处理\ncurl \"http:\u002F\u002Flocalhost:5000\u002F?url=https:\u002F\u002Fexample.com\u002Fimage.jpg&a=true&af=240\" -o output.png\n\n# 选择模型\ncurl \"http:\u002F\u002Flocalhost:5000\u002F?url=https:\u002F\u002Fexample.com\u002Fimage.jpg&model=u2net_human_seg\" -o output.png\n```\n\n参数说明：\n- `a` - 启用 Alpha 蒙版处理\n- `af` - Alpha 蒙版前景阈值（默认：240）\n- `ab` - Alpha 蒙版背景阈值（默认：10）\n- `ae` - Alpha 蒙版侵蚀大小（默认：10）\n- `az` - Alpha 蒙版基础尺寸（默认：1000）\n- `model` - 模型选择：`u2net`、`u2netp` 或 `u2net_human_seg`\n\n## 视频\n\n### 从视频中移除背景并制作透明 MOV 文件\n\n```bash\nbackgroundremover -i \"\u002Fpath\u002Fto\u002Fvideo.mp4\" -tv -o \"output.mov\"\n```\n### 处理文件夹中的所有视频\n\n现在您可以使用 `--input-folder`（`-if`）选项，从文件夹中的所有支持的图像或视频文件中移除背景。您还可以选择性地使用 `--output-folder`（`-of`）指定输出文件夹。如果未提供 `--output-folder`，输出文件将保存在输入文件夹中，并以 `output_` 为前缀。\n\n### 示例：将视频文件夹中的视频转换为透明 `.mov` 文件\n\n```bash\nbackgroundremover -if \"\u002Fpath\u002Fto\u002Fvideo-folder\" -of \"\u002Fpath\u002Fto\u002Foutput-folder\" -tv\n```\n\n您也可以结合其他选项：\n\n```bash\nbackgroundremover -if \"videos\" -of \"processed\" -m \"u2net_human_seg\" -fr 30 -tv\n```\n\n- 使用 `u2net_human_seg` 模型\n- 将视频帧率覆盖为 30 fps\n- 输出透明 `.mov` 文件到 `processed\u002F` 文件夹\n- 支持的视频格式：`.mp4`、`.mov`、`.webm`、`.ogg`、`.gif`\n- 输出文件将在输出文件夹中命名为 `output_filename.ext`\n\n### 从本地视频中移除背景并叠加到其他视频上\n\n```bash\nbackgroundremover -i \"\u002Fpath\u002Fto\u002Fvideo.mp4\" -tov -bv \"\u002Fpath\u002Fto\u002Fbackground_video.mp4\" -o \"output.mov\"\n```\n\n### 从本地视频中移除背景并叠加到图片上\n\n```bash\nbackgroundremover -i \"\u002Fpath\u002Fto\u002Fvideo.mp4\" -toi -bi \"\u002Fpath\u002Fto\u002Fbackground_image.png\" -o \"output.mov\"\n```\n\n### 从视频中移除背景并制作透明 GIF\n\n```bash\nbackgroundremover -i \"\u002Fpath\u002Fto\u002Fvideo.mp4\" -tg -o \"output.gif\"\n```\n\n### 制作遮罩文件（绿幕叠加）\n\n为 Premiere 制作遮罩文件\n\n```bash\nbackgroundremover -i \"\u002Fpath\u002Fto\u002Fvideo.mp4\" -mk -o \"output.matte.mp4\"\n```\n\n### 视频播放与兼容性\n\n**重要提示：** 透明 `.mov` 输出默认采用 ProRes 4444 编码（`prores_ks`，使用 `yuva444p10le`），该编码提供 10 位色彩和 Alpha 通道，并与专业视频编辑软件（DaVinci Resolve、Premiere、Final Cut Pro）具有极佳的兼容性。如有需要，您可以通过 `--alpha-codec` 更改编解码器。\n\n示例：\n```bash\n# 较小的带 Alpha 通道 WebM 文件（如果您的工具支持）\nbackgroundremover -i \"video.mp4\" -tv --alpha-codec libvpx-vp9 -o \"output.webm\"\n\n# 旧版 qtrle 编码（无损但文件非常大）\nbackgroundremover -i \"video.mp4\" -tv --alpha-codec qtrle -o \"output.mov\"\n```\n\n**推荐的视频播放器：**\n- **mpv**（https:\u002F\u002Fmpv.io）- 对透明视频的支持最佳（Linux、Mac、Windows）\n- **QuickTime Player**（Mac）- macOS 原生支持\n- **DaVinci Resolve** \u002F **Adobe Premiere** - 视频编辑软件中完全支持（可能需要在属性中启用 Alpha 通道）\n\n**常见问题：**\n- **VLC**：可能无法正确显示透明效果，会出现颜色失真或绿色\u002F紫色色调。\n- **Windows Media Player**：对透明度的支持有限。\n- **网页浏览器**：对 ProRes 编码的支持有限。\n\n**如果您的播放器不支持透明度的解决方法：**\n\n1. **转换为 VP9 编码的 WebM 格式（兼容性更好）：**\n   ```bash\n   ffmpeg -i output.mov -c:v libvpx-vp9 -pix_fmt yuva420p output.webm\n   ```\n\n2. **添加彩色背景（用于测试）：**\n   ```bash\n   ffmpeg -f lavfi -i color=white:s=1920x1080 -i output.mov -filter_complex 'overlay=0:0' -c:v libx264 output_with_bg.mp4\n   ```\n\n3. **直接使用透明 GIF 输出代替**（更简单但画质较低）：\n   ```bash\n   backgroundremover -i \"video.mp4\" -tg -o \"output.gif\"\n   ```\n\n### 视频高级用法\n\n更改视频帧率（默认设置为 30）\n\n```bash\nbackgroundremover -i \"\u002Fpath\u002Fto\u002Fvideo.mp4\" -fr 30 -tv -o \"output.mov\"\n```\n\n设置视频总帧数（默认设置为 -1，即移除整个视频的背景）\n\n```bash\nbackgroundremover -i \"\u002Fpath\u002Fto\u002Fvideo.mp4\" -fl 150 -tv -o \"output.mov\"\n```\n\n更改视频的 GPU 批量大小（默认设置为 1）\n\n```bash\nbackgroundremover -i \"\u002Fpath\u002Fto\u002Fvideo.mp4\" -gb 4 -tv -o \"output.mov\"\n```\n\n更改处理视频的工作线程数量（默认设置为 1）\n\n```bash\nbackgroundremover -i \"\u002Fpath\u002Fto\u002Fvideo.mp4\" -wn 4 -tv -o \"output.mov\"\n```\n\n**注意：** 在某些系统上，使用较高的工作线程数（>4）可能会导致 `ConnectionResetError` 或崩溃，这是由于多进程限制所致。如果遇到错误，请减少工作线程数或使用 `-wn 1`。最佳线程数取决于您的 CPU 核心数和可用内存。\n更改模型以使用不同的背景移除方法，可在 `u2netp`、`u2net` 或 `u2net_human_seg` 之间切换，并将帧数限制为 150\n```bash\nbackgroundremover -i \"\u002Fpath\u002Fto\u002Fvideo.mp4\" -m \"u2net_human_seg\" -fl 150 -tv -o \"output.mov\"\n```\n\n## 作为库使用\n\n### 移除背景图像\n\n```python\nfrom backgroundremover.bg import remove\n\ndef remove_bg(src_img_path, out_img_path):\n    model_choices = [\"u2net\", \"u2net_human_seg\", \"u2netp\"]\n    f = open(src_img_path, \"rb\")\n    data = f.read()\n    img = remove(data, model_name=model_choices[0],\n                 alpha_matting=True,\n                 alpha_matting_foreground_threshold=240,\n                 alpha_matting_background_threshold=10,\n                 alpha_matting_erode_structure_size=10,\n                 alpha_matting_base_size=1000)\n    f.close()\n    f = open(out_img_path, \"wb\")\n    f.write(img)\n    f.close()\n```\n\n### 仅生成二值掩码\n\n```python\nfrom backgroundremover.bg import remove\n\nf = open(\"input.jpg\", \"rb\")\ndata = f.read()\nmask = remove(data, model_name=\"u2net\", only_mask=True)\nf.close()\n\nf = open(\"mask.png\", \"wb\")\nf.write(mask)\nf.close()\n```\n\n### 将背景替换为自定义颜色\n\n```python\nfrom backgroundremover.bg import remove\n\nf = open(\"input.jpg\", \"rb\")\ndata = f.read()\n# 使用 RGB 元组指定背景颜色 (255, 0, 0) = 红色\nimg = remove(data, model_name=\"u2net\", background_color=(255, 0, 0))\nf.close()\n\nf = open(\"output.png\", \"wb\")\nf.write(img)\nf.close()\n```\n\n### 将背景替换为自定义图片\n\n```python\nfrom backgroundremover.bg import remove\n\n# 读取输入图像\nwith open(\"input.jpg\", \"rb\") as f:\n    input_data = f.read()\n\n# 读取背景图像\nwith open(\"background.jpg\", \"rb\") as f:\n    bg_data = f.read()\n\n# 移除背景并合成到背景图像上\nresult = remove(input_data, model_name=\"u2net\", background_image=bg_data)\n\n# 保存结果\nwith open(\"output.png\", \"wb\") as f:\n    f.write(result)\n```\n\n## 故障排除\n\n### “EOFError: 输入已用尽”或模型加载错误\n\n如果出现类似 `EOFError: 输入已用尽` 或模型加载失败的错误：\n\n**原因：** 模型文件下载过程中发生损坏或中断。\n\n**解决方案：**\n```bash\n# 删除损坏的模型文件\nrm ~\u002F.u2net\u002Fu2net.pth\n# 或对于其他模型：\nrm ~\u002F.u2net\u002Fu2netp.pth\nrm ~\u002F.u2net\u002Fu2net_human_seg.pth\n\n# 再次运行 backgroundremover，它会重新下载模型\nbackgroundremover -i \"your-image.jpg\" -o \"output.png\"\n```\n\n**预防措施：** 该工具现在会自动验证并重试失败的下载，但如果您使用的是旧版本中损坏的模型，则需要手动删除。\n\n### 背景未移除或部分缺失\n\n如果背景未能正确移除，或者主体的部分区域消失：\n\n1. **尝试使用不同的模型：**\n   - 对于人物\u002F肖像，使用 `u2net_human_seg`\n   - 对于一般物体，使用默认的 `u2net`\n   - 模型的选择会显著影响结果。\n\n2. **调整 alpha matting 参数：**\n   - 使用 `-a` 标志启用以获得更好的边缘检测效果。\n   - 如果某些部分被错误分类，请调整阈值参数 `-af` 和 `-ab`。\n\n3. **检查输入图像：**\n   - 确保主体与背景之间有良好的光照和对比度。\n   - 避免背景颜色与主体颜色相近的情况。\n   - 可考虑手动裁剪，以包含更明显的背景信息。\n\n### 透明度问题或颜色异常\n\n如果输出视频显示颜色失真、绿色\u002F紫色色调，或透明度无法正常工作：\n\n1. **检查您的视频播放器** - 请参阅上述“视频播放与兼容性”部分。\n2. **使用推荐的播放器**，如 mpv 或 QuickTime Player。\n3. **必要时转换为其他格式**（参见 WebM 转换示例）。\n\n### 输出文件过大\n\n透明 `.mov` 文件采用 ProRes 4444 编码，文件大小会大于输入文件。ProRes 4444 在保持 10 位色彩和透明通道的同时，比之前的 qtrle 编码提供了更好的压缩效果：\n\n- 文件大小明显小于 qtrle，但仍比普通视频大。\n- 这是高质量透明度保留的预期结果。\n- 如果您的工具支持，可以使用 `--alpha-codec libvpx-vp9` 生成较小的 `.webm` 文件。\n\n### 质量较差或结果不准确\n\n背景移除的质量取决于以下因素：\n\n1. **输入质量** - 更高的分辨率和更好的光照条件有助于提高效果。\n2. **主体复杂度** - 简单且轮廓清晰的主体效果最佳。\n3. **模型局限性** - AI 模型可能难以处理以下情况：\n   - 主体与背景颜色非常接近。\n   - 复杂的头发或毛发细节。\n   - 透明或反光物体。\n   - 模型未训练过的特殊主体。\n\n**提升效果的建议：**\n- 对于人像主体，专门使用 `u2net_human_seg`。\n- 对于复杂边缘，启用 alpha matting 参数 `-a`。\n- 拍摄时确保主体与背景之间有足够的对比度。\n- 尝试不同的 alpha matting 参数（`-ae`、`-af`、`-ab`）。\n\n## 测试\n\n目前该项目尚未实现自动化测试用例。测试均通过手动方式，使用示例图像和视频进行。\n\n### 手动测试\n\n测试 backgroundremover 功能的方法如下：\n\n**测试图像背景移除：**\n```bash\n# 基本测试\nbackgroundremover -i \"test_image.jpg\" -o \"output.png\"\n\n# 启用 alpha matting 的测试\nbackgroundremover -i \"test_image.jpg\" -a -ae 15 -o \"output.png\"\n\n# 测试掩码生成\nbackgroundremover -i \"test_image.jpg\" -om -o \"mask.png\"\n\n# 测试自定义背景颜色\nbackgroundremover -i \"test_image.jpg\" -bc \"0,255,0\" -o \"output.png\"\n```\n\n**测试视频处理：**\n```bash\n# 测试透明视频\nbackgroundremover -i \"test_video.mp4\" -tv -o \"output.mov\"\n\n# 测试抠像\nbackgroundremover -i \"test_video.mp4\" -mk -o \"matte.mov\"\n\n# 测试透明 GIF\nbackgroundremover -i \"test_video.mp4\" -tg -o \"output.gif\"\n```\n\n**测试 HTTP 服务器：**\n```bash\n# 启动服务器\nbackgroundremover-server --port 5000\n\n# 使用 curl 测试（在另一个终端）\ncurl -X POST -F \"file=@test_image.jpg\" http:\u002F\u002Flocalhost:5000\u002F -o output.png\n```\n\n### 贡献测试\n\n使用 pytest 或 unittest 实现自动化测试将是对该项目的重要贡献。测试用例应涵盖：\n- 不同格式图像的处理（JPG、PNG、HEIC）\n- 不同编解码器的视频处理\n- CLI 参数验证\n- HTTP API 端点\n- 模型加载与推理\n- 错误处理\n\n## 待办事项\n\n### 已完成\n- ✅ HTTP API 服务器（使用 `backgroundremover-server`）\n- ✅ 全面的文档和故障排除指南\n- ✅ Docker 支持及模型持久化\n- ✅ HEIC\u002FHEIF 图像格式支持\n- ✅ 管道支持（stdin\u002Fstdout）\n- ✅ 自定义背景颜色和图片\n- ✅ 二值掩码输出\n- ✅ 文件夹批量处理\n\n### 进行中 \u002F 未来功能\n- 支持更多模型（ISNet、BiRefNet、U2Net 衣物分割）\n- CoreML 支持，用于 Apple Silicon 加速\n- 独立可执行文件（无需安装 Python）\n- 自动化测试套件\n- 视频流实时背景移除\n- 将视频处理逻辑迁移到图像处理，以更好地利用 GPU\n- 提供结果反馈以改进训练数据集\n- 支持自定义\u002F用户提供的模型\n- Google Colab 笔记本\n\n欢迎贡献！详情请查看公开议题。\n\n### 拉取请求\n\n已接受\n\n### 如果你喜欢这个库\n\n请分享我们的项目链接 [BackgroundRemoverAI.com](https:\u002F\u002Fbackgroundremoverai.com) 或本仓库，并告诉大家你很喜欢它或正在使用它。\n\n### 项目背景\n\n我们在整合了其他项目的部分代码后，通过在 Superuser 等平台上发布悬赏问题来添加了一些自定义功能。此外，我们还曾在 HackerNews 上呼吁将图像处理部分开源，因此决定进一步扩展到视频处理，并增加了一些额外的功能。\n\n\n\n### 参考资料\n\n- https:\u002F\u002Farxiv.org\u002Fpdf\u002F2005.09007.pdf\n- https:\u002F\u002Fgithub.com\u002FNathanUA\u002FU-2-Net\n- https:\u002F\u002Fgithub.com\u002Fpymatting\u002Fpymatting\n- https:\u002F\u002Fgithub.com\u002Fdanielgatis\u002Frembg\n- https:\u002F\u002Fgithub.com\u002Fecsplendid\u002Frembg-greenscreen\n- https:\u002F\u002Fsuperuser.com\u002Fquestions\u002F1647590\u002Fhave-ffmpeg-merge-a-matte-key-file-over-the-normal-video-file-removing-the-backg\n- https:\u002F\u002Fsuperuser.com\u002Fquestions\u002F1648680\u002Fffmpeg-alphamerge-two-videos-into-a-gif-with-transparent-background\u002F1649339?noredirect=1#comment2522687_1649339\n- https:\u002F\u002Fsuperuser.com\u002Fquestions\u002F1649817\u002Fffmpeg-overlay-a-video-after-alphamerging-two-others\u002F1649856#1649856\n\n### 许可证\n\n- 版权所有 © 2021 至今 [Johnathan Nader](https:\u002F\u002Fgithub.com\u002Fnadermx)\n- 版权所有 © 2020 至今 [Lucas Nestler](https:\u002F\u002Fgithub.com\u002FClashLuke)\n- 版权所有 © 2020 至今 [Dr. Tim Scarfe](https:\u002F\u002Fgithub.com\u002Fecsplendid)\n- 版权所有 © 2020 至今 [Daniel Gatis](https:\u002F\u002Fgithub.com\u002Fdanielgatis)\n\n代码采用 [MIT 许可证](.\u002FLICENSE.txt) 授权  \n模型采用 [Apache 2.0 许可证](.\u002Fmodels\u002Flicense) 授权","# BackgroundRemover 快速上手指南\n\nBackgroundRemover 是一款基于 AI 的命令行工具，支持从图片和视频中移除背景。它利用 U2-Net 模型自动检测主体，并生成带有透明通道的输出文件。\n\n## 环境准备\n\n在开始之前，请确保您的系统满足以下要求：\n\n*   **操作系统**：Linux, macOS 或 Windows\n*   **Python**：版本 >= 3.6（建议安装对应的 `python3.x-dev` 开发包）\n*   **FFmpeg**：版本 4.4+（视频处理必备）\n*   **PyTorch**：需预先安装稳定的 `torch` 和 `torchvision`\n\n### 依赖安装说明\n\n1.  **安装 PyTorch**\n    访问 [PyTorch 官网](https:\u002F\u002Fpytorch.org) 获取适合您环境的命令。\n    \n    *   **CPU 版本（默认）**：\n        ```bash\n        pip3 install torch torchvision --index-url https:\u002F\u002Fdownload.pytorch.org\u002Fwhl\u002Fcpu\n        ```\n    *   **GPU 加速版本（推荐，速度提升 5-10 倍）**：\n        ```bash\n        # CUDA 11.8 示例\n        pip3 install torch torchvision --index-url https:\u002F\u002Fdownload.pytorch.org\u002Fwhl\u002Fcu118\n        # 或 CUDA 12.1\n        pip3 install torch torchvision --index-url https:\u002F\u002Fdownload.pytorch.org\u002Fwhl\u002Fcu121\n        ```\n\n2.  **安装 FFmpeg 和 Python 开发包**\n    *   **Ubuntu\u002FDebian**:\n        ```bash\n        sudo apt install ffmpeg python3-dev\n        ```\n    *   **macOS (Homebrew)**:\n        ```bash\n        brew install ffmpeg\n        ```\n    *   **Windows**: 请手动下载并安装 FFmpeg，将其添加到系统环境变量 PATH 中。\n\n## 安装步骤\n\n推荐使用 pip 进行安装：\n\n```bash\npip install --upgrade pip\npip install backgroundremover\n```\n\n> **注意**：首次运行时，程序会自动下载所需的 U2-Net 模型文件。\n\n### Docker 安装（可选）\n如果您希望隔离环境或使用 Docker：\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fnadermx\u002Fbackgroundremover.git\ncd backgroundremover\ndocker build -t bgremover .\n\n# 创建别名以便使用（推荐挂载模型目录以避免重复下载）\nmkdir -p ~\u002F.u2net\nalias backgroundremover='docker run -it --rm --shm-size=2g -v \"$(pwd):\u002Ftmp\" -v \"$HOME\u002F.u2net:\u002Froot\u002F.u2net\" bgremover:latest'\n```\n*注：视频处理需要较大的共享内存，Docker 运行请务必添加 `--shm-size=2g` 参数。*\n\n## 基本使用\n\n安装完成后，即可在终端直接使用 `backgroundremover` 命令。\n\n### 1. 移除图片背景\n将本地图片的背景移除，输出为透明 PNG：\n\n```bash\nbackgroundremover -i \"\u002Fpath\u002Fto\u002Fimage.jpeg\" -o \"output.png\"\n```\n\n*   `-i`: 输入文件路径\n*   `-o`: 输出文件路径\n*   支持格式：`.jpg`, `.jpeg`, `.png`, `.heic`, `.heif`\n\n### 2. 移除视频背景\n将视频背景移除，生成带透明通道的 `.mov` 文件（默认使用 ProRes 4444 编码，兼容专业剪辑软件）：\n\n```bash\nbackgroundremover -i \"\u002Fpath\u002Fto\u002Fvideo.mp4\" -tv -o \"output.mov\"\n```\n\n*   `-tv`: 标记为处理视频并输出透明视频\n*   支持格式：`.mp4`, `.mov`, `.webm`, `.ogg`, `.gif`\n\n### 3. 批量处理文件夹\n一次性处理文件夹内的所有图片或视频：\n\n```bash\n# 处理图片文件夹\nbackgroundremover -if \"\u002Fpath\u002Fto\u002Fimage-folder\" -of \"\u002Fpath\u002Fto\u002Foutput-folder\"\n\n# 处理视频文件夹并输出透明 MOV\nbackgroundremover -if \"\u002Fpath\u002Fto\u002Fvideo-folder\" -of \"\u002Fpath\u002Fto\u002Foutput-folder\" -tv\n```\n\n### 常用高级选项简述\n*   **更换模型**：针对人像优化可使用 `-m \"u2net_human_seg\"`，追求速度可使用 `-m \"u2netp\"`。\n*   **边缘优化**：添加 `-a` 参数启用 Alpha Matting 以获得更自然的边缘。\n*   **替换背景**：使用 `-bc \"R,G,B\"` 替换为纯色，或 `-bi \"bg.jpg\"` 替换为指定图片。","某电商运营团队需要为数百款新品快速制作去背商品图与动态展示视频，以适配多平台营销素材。\n\n### 没有 backgroundremover 时\n- 设计师必须逐张在 Photoshop 中手动抠图，处理几百张高清图需耗费数天时间，人力成本极高。\n- 面对产品演示视频，传统工具难以逐帧精准分离前景与背景，往往只能放弃视频素材或花费巨资外包。\n- 缺乏统一的命令行自动化流程，无法将去背任务集成到现有的批量处理脚本中，工作流断裂且低效。\n- 商业 API 服务按次收费，处理海量图片与视频时费用高昂，且存在数据上传隐私泄露的风险。\n\n### 使用 backgroundremover 后\n- 通过简单的命令行指令即可批量处理所有图片，利用 GPU 加速将原本几天的工作量缩短至几十分钟。\n- 直接支持视频文件输入，AI 自动逐帧识别并移除背景，轻松生成高质量的商品动态展示素材。\n- 提供标准的 CLI 接口与 Docker 支持，可无缝嵌入自动化运维脚本，实现从上传到输出的全流程无人值守。\n- 作为免费开源工具，本地部署运行彻底消除了按量计费成本，同时确保原始素材数据完全保留在本地服务器。\n\nbackgroundremover 将繁琐的视觉素材预处理转化为高效的自动化流程，让中小团队也能以零成本拥有电影级的去背生产能力。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fnadermx_backgroundremover_4f28b6dc.png","nadermx","Johnathan Nader","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Fnadermx_184b011c.jpg",null,"https:\u002F\u002Fjohn.nader.mx","https:\u002F\u002Fgithub.com\u002Fnadermx",[80,84,88],{"name":81,"color":82,"percentage":83},"Python","#3572A5",99.4,{"name":85,"color":86,"percentage":87},"Dockerfile","#384d54",0.6,{"name":89,"color":90,"percentage":91},"Batchfile","#C1F12E",0.1,7849,647,"2026-04-16T12:10:25","MIT","Linux, macOS, Windows","非必需（支持 CPU 模式）。若使用 GPU 加速，需 NVIDIA 显卡并安装匹配的 CUDA 版本（文档示例提及 CUDA 11.8 和 12.1），显存不足时可通过参数减少批次大小。","未说明（视频处理多进程模式建议增加共享内存，Docker 环境下推荐 --shm-size=2g）",{"notes":100,"python":101,"dependencies":102},"1. 必须同时安装 Python 及其对应的 dev 开发包（如 python3.10 配 python3.10-dev）。2. 首次运行会自动下载 u2net 系列模型文件。3. 视频处理依赖 ffmpeg 4.4+ 版本。4. Docker 运行视频任务时需设置共享内存大小（--shm-size=2g）以避免多进程错误。5. 透明视频输出默认为 ProRes 4444 编码，部分播放器（如 VLC）可能无法正确显示透明度。","3.6+",[103,104,105,106,107],"torch","torchvision","ffmpeg>=4.4","python-dev (对应 Python 版本的开发包)","pillow-heif (可选，用于 HEIC\u002FHEIF 格式)",[14,13,109,15],"视频",[111,65,112,113,114,115,116,117,118,119,120,121,122],"background-remover","removebackground","remove-background","remove-background-image","remove-background-video","background-removal","python","video","pytorch","video-editing","photo-editing","ai","2026-03-27T02:49:30.150509","2026-04-17T08:24:15.996178",[126,131,136,141,146,151],{"id":127,"question_zh":128,"answer_zh":129,"source_url":130},37133,"运行 backgroundremover 时遇到 'RuntimeError: storage has wrong byte size' 错误怎么办？","该错误通常由 Python 环境或依赖项安装顺序不当引起。请按照以下顺序在干净的系统中重新安装：\n1. `apt-get install python3.x` (替换 x 为你的版本号，如 3.10)\n2. `apt-get install python3.x-dev`\n3. `apt-get install pip`\n4. `pip install backgroundremover`\n确保同时安装了 python3 和对应的 dev 包，然后重试命令。","https:\u002F\u002Fgithub.com\u002Fnadermx\u002Fbackgroundremover\u002Fissues\u002F97",{"id":132,"question_zh":133,"answer_zh":134,"source_url":135},37134,"使用 -tov 参数叠加透明视频到背景视频时报错 'invalid \u003Clambda> value' 如何解决？","这是一个已知的命令行参数解析问题。维护者已确认该问题并修复了相关的 ffmpeg 命令逻辑。如果您遇到此错误，请确保您使用的是最新版本的 backgroundremover。如果问题依旧，可能是参数传递方式有误，建议检查是否直接传递了文件名作为参数值，或者升级到修复后的版本。","https:\u002F\u002Fgithub.com\u002Fnadermx\u002Fbackgroundremover\u002Fissues\u002F28",{"id":137,"question_zh":138,"answer_zh":139,"source_url":140},37135,"生成的 MOV 文件体积过大且无法在 Mac 的 QuickTime 中播放怎么办？","该问题已在 v0.3.8 版本中修复。旧版本生成的 MOV 文件可能使用了不兼容的编码导致文件巨大且无法播放。请将 backgroundremover 更新到最新版本（v0.3.8 或更高），然后重新运行命令生成视频。如果更新后问题仍然存在，请提交包含日志和样本输入的新工单。","https:\u002F\u002Fgithub.com\u002Fnadermx\u002Fbackgroundremover\u002Fissues\u002F49",{"id":142,"question_zh":143,"answer_zh":144,"source_url":145},37136,"处理视频或 GIF 输出时生成 0kb 文件或失败的原因是什么？","这通常与输入文件的具体格式、FFmpeg 版本兼容性或特定代码路径中的错误有关。维护者需要具体的示例视频来复现和调试此问题。如果您遇到此情况，请尝试提供出错的源视频文件给开发者，或者检查您的 FFmpeg 版本（建议使用较新版本如 5.1.1+），并确保命令行中没有静默的错误被忽略。目前该问题在部分环境下（如 Windows Python 3.13）仍有报告，需等待后续修复。","https:\u002F\u002Fgithub.com\u002Fnadermx\u002Fbackgroundremover\u002Fissues\u002F41",{"id":147,"question_zh":148,"answer_zh":149,"source_url":150},37137,"调用 API 移除视频背景时出现 'JSONDecodeError' 错误是怎么回事？","此错误通常表示 API 返回了非 JSON 格式的内容，可能是因为账户额度不足、API 密钥无效或服务器端临时问题。首先检查您的 API 密钥是否正确，并确认账户中有足够的积分（Credits）。如果积分充足仍报错，可能是服务端故障，建议联系维护者检查账户状态或稍后重试。有用户反馈在维护者调整账户额度后问题解决。","https:\u002F\u002Fgithub.com\u002Fnadermx\u002Fbackgroundremover\u002Fissues\u002F20",{"id":152,"question_zh":153,"answer_zh":154,"source_url":130},37138,"如何正确安装 backgroundremover 以避免常见的运行时错误？","为了避免诸如 'storage has wrong byte size' 等运行时错误，请严格遵守以下安装步骤：\n1. 安装 Python 3 及其开发包：`sudo apt install python3.x python3.x-dev`\n2. 安装 pip：`sudo apt install pip`\n3. 安装工具：`pip install backgroundremover`\n不要跳过 `-dev` 包的安装，且务必按顺序执行。如果在旧环境中遇到问题，建议在新鲜安装的系统中重试。",[156,161,166,171,176,181,186,191,196,201,206,211,216,221,226,231,236,241,246,251],{"id":157,"version":158,"summary_zh":159,"released_at":160},297612,"v0.4.1","## 亮点\n\n- **ProRes 4444 默认**：透明视频输出现默认使用 `prores_ks` 编码器，并采用 `yuva444p10le` 格式（10位色深带 Alpha 通道），而非之前的 `qtrle`。新设置带来了更优的压缩效果、更高的色彩保真度以及更好的非线性编辑软件兼容性（如 DaVinci Resolve、Premiere、Final Cut Pro）。旧的 `qtrle` 编码器仍可通过 `--alpha-codec qtrle` 参数启用。\n\n- **智能工作进程扩展**：工作进程数（`-wn`）现会根据实际 GPU 显存动态限制，而非采用硬性上限。工具会计算每个工作进程所需的显存用量（包括 CUDA 上下文、模型、JIT 优化后的代码及批次张量），从而避免因过度分配导致的卡顿或崩溃。\n\n- **用于锐利边缘的掩码阈值**：新增 `-mt`\u002F`--mask-threshold` 选项，可根据指定阈值（0–255）将 Alpha 掩码二值化，以生成清晰锐利的剪切边缘——特别适用于卡通风格图像、标志和插画。\n\n- **设备诊断信息**：启动时会打印检测到的设备类型、GPU 型号及显存容量，方便用户确认 GPU 加速是否正常运行。\n\n## 新增 CLI 参数\n\n| 参数 | 描述 |\n|------|-------------|\n| `-mt 128` \u002F `--mask-threshold 128` | 将掩码二值化以获得锐利边缘（0–255） |\n\n## 修复内容\n\n- #181：高工作进程数时视频处理会卡死——现已根据 GPU 显存容量动态限制工作进程数量。\n- #122：卡通风格图像的边缘过于柔和模糊——新增 `--mask-threshold` 选项，可生成清晰锐利的剪切边缘。\n- #145：未显示 GPU 使用情况——现会在启动时打印设备信息（CUDA\u002FMPS\u002FCPU），并附上 GPU 型号及显存容量。\n\n## 破坏性变更\n\n- 默认透明视频编码器已从 `qtrle` 更改为 `prores_ks`。新输出文件体积更小、色彩表现更好，但需使用支持 ProRes 的播放器进行播放。若需恢复旧行为，请使用 `--alpha-codec qtrle`。\n\n## 升级方法\n\n```bash\npip install --upgrade backgroundremover\n```","2026-02-17T20:42:19",{"id":162,"version":163,"summary_zh":164,"released_at":165},297613,"v0.3.8","亮点\n\n  - 透明输出的视频流水线稳定性与兼容性得到提升。\n\n修复\n\n  - #44：使用精确检测到的帧率以减少 Alpha 蒙版漂移。\n  - #85：显式映射经过滤的视频及可选音频，避免输出仅为“纯音频”。\n  - #49、#86：新增 --alpha-codec 和 --alpha-pix-fmt 选项，用于控制 Alpha 视频编码；无损默认仍为 qtrle。\n  - #98、#88、#152：更稳健的 Alpha 合成流水线和编码选项，提升了对问题视频的处理效果。\n  - #168：修正了 transparentvideooverimage 中的蒙版使用方式，确保 Alpha 始终一致应用。\n\n用户可见变更\n\n  - 新增 CLI 标志：--alpha-codec（auto、qtrle、prores_ks、libvpx-vp9）和 --alpha-pix-fmt。\n  - 更新 README，添加 Alpha 编码器指南及帧率覆盖示例。","2025-12-21T00:58:45",{"id":167,"version":168,"summary_zh":169,"released_at":170},297614,"v0.3.7","修复需求最低","2025-12-10T03:18:13",{"id":172,"version":173,"summary_zh":174,"released_at":175},297615,"0.3.6","0.3.6 版本更新内容：\n- 添加了 GUI 应用程序（PR #175）\n- 背景图片现为可选，且不再因标准输入而卡死（PR #179）\n- 改进了命令行界面的验证，并提供了更友好的错误提示信息\n- 优化了多进程错误处理\n- 当工作进程数量较高时会发出警告","2025-12-10T01:58:25",{"id":177,"version":178,"summary_zh":179,"released_at":180},297616,"v0.3.5","已修复\n\n  Docker 相关问题\n\n  - 修复了在 Docker 中运行时的错误 (#176)\n  - 解决了 Docker 总是下载模型的问题 (#105)\n  - 修复了 Docker 中视频背景移除功能无法正常工作的问题 (#120)\n\n  视频处理\n\n  - 修复了无法生成透明 .mov 文件的问题 (#135)\n  - 解决了仅生成掩码而未移除视频的问题 (#134)\n  - 修复了创建透明 mov 文件时出现“无效参数”错误的问题 (#115)\n  - 修复了在图片上叠加透明图层时出现“无效值”错误的问题 (#116)\n\n  运行时错误\n\n  - 修复了 RuntimeError: operator torchvision::nms 不存在 的错误 (#172)\n  - 解决了“DEBUG: 待检查路径: C:\\Users\\kroupu2net\\u2net.pth”错误 (#164)\n  - 修复了“输入用尽”错误 (#110)\n\n  API 问题\n\n  - 修复了 API 旋转图片时出现错误的问题 (#144)\n\n  平台支持\n\n  - 解决了 torchaudio 在 ARM64 架构上的兼容性问题 (#162)\n\n  新增\n\n  功能\n\n  - 增加了对管道读取\u002F输出的支持 (#170)\n  - 增加了对 HEIC 图像格式的支持 (#151)\n  - 增加了使用自定义颜色（蓝色、红色等）填充的功能 (#74)\n  - 增加了为图片生成掩码的功能 (#67)\n\n  文档\n\n  - 澄清了如何运行测试用例的方法 (#169)\n  - 改进了关于如何将背景图片与普通图片一起使用的说明 (#113)\n\n  ---\n  已解决问题总数：18","2025-10-28T23:21:17",{"id":182,"version":183,"summary_zh":184,"released_at":185},297617,"v0.3.4","在需求和导入 moviepy 时遇到了问题。","2025-04-08T21:45:00",{"id":187,"version":188,"summary_zh":189,"released_at":190},297618,"v0.3.2","MoviePy 导入出现问题。升级版本。","2025-04-08T21:01:00",{"id":192,"version":193,"summary_zh":194,"released_at":195},297619,"v0.3.1","修复长期存在的视频导入问题。升级 moviepy。","2025-04-08T20:09:37",{"id":197,"version":198,"summary_zh":199,"released_at":200},297620,"v0.3.0","关闭了议题 #99、#143、#130。\n\n新增按文件夹批量处理视频或图片的功能。已更新 README 文件以反映此更改。","2025-04-04T17:31:14",{"id":202,"version":203,"summary_zh":204,"released_at":205},297621,"v0.2.9","将 https:\u002F\u002Fgithub.com\u002Fnadermx\u002Fbackgroundremover\u002Fissues\u002F155 添加到版本中。固定 moviepy 的错误。","2024-12-26T17:44:27",{"id":207,"version":208,"summary_zh":209,"released_at":210},297622,"v0.2.8","Proper release of GPU cache thanks @Isalia20 \r\n\r\nAlso close https:\u002F\u002Fgithub.com\u002Fnadermx\u002Fbackgroundremover\u002Fissues\u002F142 issue between mismatch of version 0.2.7 and the pypi distribution.","2024-05-01T21:47:20",{"id":212,"version":213,"summary_zh":214,"released_at":215},297623,"v0.2.7","Fix an issue bad naming of variable.  A thank you to @ya0guang\r\n\r\nUpdate readme with how to use backgroundremover as a library and made a pull request fixing the circular imports for it to work correctly.  A thank you to @ahmad88me\r\n\r\nFix an issue with moviepy requirments.\r\n","2024-04-12T19:12:06",{"id":217,"version":218,"summary_zh":219,"released_at":220},297624,"v0.2.6","Take out shlex, put commands from subprocess into list before. ","2023-12-06T01:06:04",{"id":222,"version":223,"summary_zh":224,"released_at":225},297625,"v0.2.5","Let ffmpeg log alphamerge to see if helps shine 0kb error","2023-08-15T22:37:58",{"id":227,"version":228,"summary_zh":229,"released_at":230},297626,"v0.2.4","Closes issue https:\u002F\u002Fgithub.com\u002Fnadermx\u002Fbackgroundremover\u002Fissues\u002F84","2023-07-18T15:40:03",{"id":232,"version":233,"summary_zh":234,"released_at":235},297627,"v0.2.3","Fixes https:\u002F\u002Fgithub.com\u002Fnadermx\u002Fbackgroundremover\u002Fissues\u002F78 and https:\u002F\u002Fgithub.com\u002Fnadermx\u002Fbackgroundremover\u002Fissues\u002F80","2023-05-29T01:34:06",{"id":237,"version":238,"summary_zh":239,"released_at":240},297628,"v0.2.2","Fix issue #18 for Mac users\r\nFix issue with inputs of videos with special characters\r\nFix spelling issues in read me\r\n","2023-05-16T04:33:09",{"id":242,"version":243,"summary_zh":244,"released_at":245},297629,"v0.2.1","Fix issues with windows. \r\nFix issues with download files from google vs github.\r\nFix issue with remove background from local video and overlay it over an image\r\nFix issue with frame_rate detection on some videos","2023-05-05T19:57:37",{"id":247,"version":248,"summary_zh":249,"released_at":250},297630,"v0.1.9","Fix issue with u2net import, where would re download existing libraries on system.","2021-08-13T15:33:58",{"id":252,"version":253,"summary_zh":254,"released_at":255},297631,"v0.1.8","Fix relative import issue","2021-08-13T14:33:56"]