{"id":31373899,"url":"https://github.com/alh477/usb-cam-bash","last_synced_at":"2026-05-14T12:35:49.921Z","repository":{"id":316556904,"uuid":"1063878240","full_name":"ALH477/usb-cam-bash","owner":"ALH477","description":"A robust, configurable Bash script for capturing raw or lossless video footage from multiple USB cameras and audio from a USB microphone using FFmpeg on Linux systems. Optimized for laptops, ","archived":false,"fork":false,"pushed_at":"2025-09-25T08:54:21.000Z","size":33,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-25T10:26:19.207Z","etag":null,"topics":["bash","usb-camera"],"latest_commit_sha":null,"homepage":"https://DeMoD.ltd","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ALH477.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-25T08:35:42.000Z","updated_at":"2025-09-25T08:54:24.000Z","dependencies_parsed_at":"2025-09-25T10:26:23.666Z","dependency_job_id":null,"html_url":"https://github.com/ALH477/usb-cam-bash","commit_stats":null,"previous_names":["alh477/usb-cam-bash"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/ALH477/usb-cam-bash","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ALH477%2Fusb-cam-bash","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ALH477%2Fusb-cam-bash/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ALH477%2Fusb-cam-bash/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ALH477%2Fusb-cam-bash/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ALH477","download_url":"https://codeload.github.com/ALH477/usb-cam-bash/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ALH477%2Fusb-cam-bash/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33025298,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-13T13:14:54.681Z","status":"online","status_checked_at":"2026-05-14T02:00:06.663Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bash","usb-camera"],"created_at":"2025-09-27T23:06:37.277Z","updated_at":"2026-05-14T12:35:49.887Z","avatar_url":"https://github.com/ALH477.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# USB Camera and Microphone Recorder for Linux\n\n[![License: GPLv3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)\n\nA robust, configurable Bash script for capturing raw or lossless video footage from multiple USB cameras and audio from a USB microphone using FFmpeg on Linux systems. Optimized for laptops, it supports dynamic device detection, auto-configuration, live previews, and overlays. Ideal for professional recording setups, surveillance, or content creation.\n\n## Features\n\n- **Dynamic Device Detection**: Automatically detects USB cameras via `v4l2-ctl` and microphones via PulseAudio/ALSA, with fallbacks to `lsusb`.\n- **Auto-Detection of Camera Specs**: Probes maximum resolution and FPS per camera using `v4l2-ctl --list-formats-ext`, now with improved FPS selection for same-resolution formats.\n- **Flexible Recording Modes**:\n  - Default: Lossless FFV1 in MKV container (compressed but high-quality).\n  - Raw copy mode (AVI) for unprocessed footage, with warning if overlays force encoding.\n- **Live Preview**: Optional scaled previews with `ffplay` (e.g., half-size to reduce CPU load), with combined overlay and scaling filters to prevent conflicts.\n- **Overlays**: Add custom text (e.g., \"DeMoD LLC\") with real-time timestamps, requiring FFV1 encoding.\n- **Separate Outputs**: One file per camera/audio stream for easy post-processing.\n- **JSON Configuration**: Override defaults via a simple JSON file.\n- **Enhanced Error Handling**: \n  - Tests audio devices with detailed error output; skips on failure.\n  - Validates process starts (PIDs) for recordings and previews.\n  - Clean shutdowns via SIGINT for FFmpeg, with duration handled natively (`-t` option).\n  - Checks for `bc` dependency for preview scaling; defaults to full scale if absent.\n  - Warns on preview/recording device conflicts with a pause to close previews.\n- **NixOS-Compatible**: Handles common issues like disabled ALSA/PulseAudio.\n\n## Requirements\n\n- **Core Dependencies**:\n  - FFmpeg (with V4L2, ALSA/PulseAudio support; `ffmpeg-full` on NixOS).\n  - `v4l2-ctl` (from `v4l-utils`).\n- **Optional**:\n  - `ffplay` (for previews).\n  - `pactl`/`arecord` (for audio detection).\n  - `jq` (for JSON config parsing).\n  - `udevadm` (for enhanced USB probing).\n  - `bc` (for preview scaling calculations).\n- **System**: Linux with USB camera/mic support. Tested on Ubuntu, Fedora, and NixOS.\n\nInstall on NixOS (add to `configuration.nix`):\n```nix\nenvironment.systemPackages = with pkgs; [\n  ffmpeg-full\n  v4l-utils\n  pulseaudio  # Or pipewire for audio\n  bc\n];\nsound.enable = true;\nhardware.pulseaudio.enable = true;\n```\n\n## Installation\n\n1. Clone or download the repository:\n   ```\n   git clone \u003crepo-url\u003e\n   cd \u003crepo-dir\u003e\n   chmod +x record.sh\n   ```\n\n2. Ensure dependencies are installed (e.g., `sudo apt install ffmpeg v4l-utils jq bc` on Debian/Ubuntu).\n\n## Usage\n\nRun the script interactively:\n```\n./record.sh [base_name] [--raw] [--duration SECONDS] [--config config.json]\n```\n\n- **`base_name`**: Output prefix (default: `recording`).\n- **`--raw`**: Use raw copy mode (AVI) instead of FFV1 (MKV); ignored with overlays.\n- **`--duration SECONDS`**: Auto-stop after time (e.g., 300 for 5 minutes), now using FFmpeg's native `-t` for clean stops.\n- **`--config config.json`**: Load JSON config (see below).\n\nThe script prompts for:\n- Auto-detect camera specs (y/n).\n- Custom resolution/FPS confirmation.\n- Text overlay with timestamp (y/n; default text: \"DeMoD LLC\").\n- Scaled preview (y/n; e.g., 0.5 for half-size), with pause to close previews before recording.\n- Audio skip if device test fails.\n\nPress `q` + Enter during recording to stop, then confirm to save files. Ctrl+C also triggers clean shutdown.\n\n### Example Output Files\nIn the script's directory:\n- `recording_cam0.mkv` (FFV1 video).\n- `recording_cam1.mkv` (second camera).\n- `recording_audio.flac` (lossless audio).\n\n### JSON Configuration Example\n\nCreate `config.json`:\n```json\n{\n  \"default_framerate\": 60,\n  \"default_video_size\": \"1280x720\",\n  \"input_format\": \"mjpeg\",\n  \"thread_queue_size\": 2048,\n  \"font_file\": \"/usr/share/fonts/truetype/dejavu/DejaVuSansMono.ttf\",\n  \"default_overlay_text\": \"Your Company LLC\"\n}\n```\n\nRun: `./record.sh my_recording --config config.json`\n\n## Troubleshooting\n\n- **\"Device or resource busy\"**: Preview and recording can't share devices. Close `ffplay` windows via prompt or disable preview.\n- **MKV Muxer Error**: Rare in full builds; script uses `-f matroska` as workaround.\n- **Audio Test Fails**: Detailed error output shown; enable sound in NixOS config or skip audio via prompt.\n- **No Cameras Detected**: Run `v4l2-ctl --list-devices` manually; ensure USB permissions (`sudo usermod -aG video $USER`).\n- **High CPU/Overheating**: Lower FPS/resolution, use SSD output, or raw mode.\n- **Overlays Not Rendering**: Install DejaVu fonts (`sudo apt install fonts-dejavu-core`).\n- **Preview Scaling Fails**: Ensure `bc` is installed; otherwise, defaults to full scale.\n\nFor sync issues in post-processing, use tools like DaVinci Resolve or `ffmpeg` with timestamps.\n\n## Contributing\n\nFork, branch, and submit PRs for features/bugfixes. Tests appreciated!\n\n## Credits\n\n- Developed with assistance from **Grok 3** by xAI.\n- Created by **Asher LeRoy**, Founder of DeMoD LLC.\n\n## License\n\nThis project is licensed under the GNU General Public License v3.0 (GPLv3) - see [LICENSE](LICENSE) for details.\n\n```\nCopyright (C) 2025 Asher LeRoy (DeMoD LLC)\n\nThis program is free software: you can redistribute it and/or modify\nit under the terms of the GNU General Public License as published by\nthe Free Software Foundation, either version 3 of the License, or\n(at your option) any later version.\n\nThis program is distributed in the hope that it will be useful,\nbut WITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\nGNU General Public License for more details.\n\nYou should have received a copy of the GNU General Public License\nalong with this program.  If not, see \u003chttps://www.gnu.org/licenses/\u003e.\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falh477%2Fusb-cam-bash","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falh477%2Fusb-cam-bash","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falh477%2Fusb-cam-bash/lists"}