{"id":29938028,"url":"https://github.com/open-technology-foundation/vrecord","last_synced_at":"2026-05-08T09:34:46.297Z","repository":{"id":307254538,"uuid":"1028877699","full_name":"Open-Technology-Foundation/vrecord","owner":"Open-Technology-Foundation","description":"A robust command-line voice recording tool for Linux that supports pause/resume functionality and automatic MP3 conversion and optional transcription.","archived":false,"fork":false,"pushed_at":"2026-02-10T07:30:29.000Z","size":146,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-10T13:35:03.363Z","etag":null,"topics":["audio-recording","bash","ffmpeg","voice-recorder"],"latest_commit_sha":null,"homepage":"https://yatti.id/","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Open-Technology-Foundation.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-07-30T07:37:13.000Z","updated_at":"2026-02-10T07:30:33.000Z","dependencies_parsed_at":"2025-07-30T09:37:59.413Z","dependency_job_id":"8dbb5a40-8669-453f-8803-668563c3aca1","html_url":"https://github.com/Open-Technology-Foundation/vrecord","commit_stats":null,"previous_names":["open-technology-foundation/vrecord"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Open-Technology-Foundation/vrecord","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Open-Technology-Foundation%2Fvrecord","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Open-Technology-Foundation%2Fvrecord/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Open-Technology-Foundation%2Fvrecord/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Open-Technology-Foundation%2Fvrecord/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Open-Technology-Foundation","download_url":"https://codeload.github.com/Open-Technology-Foundation/vrecord/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Open-Technology-Foundation%2Fvrecord/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32775078,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-08T08:22:46.396Z","status":"ssl_error","status_checked_at":"2026-05-08T08:22:45.650Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["audio-recording","bash","ffmpeg","voice-recorder"],"created_at":"2025-08-02T23:16:33.073Z","updated_at":"2026-05-08T09:34:46.285Z","avatar_url":"https://github.com/Open-Technology-Foundation.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# vrecord - Voice Recorder with Resume Capability\n\nCommand-line voice recorder for Linux with pause/resume via signals, continue/append to existing recordings, automatic MP3 conversion, and optional transcription.\n\n## Quick Install\n\n```bash\n# One-liner installation (uses sudo)\ncurl -fsSL https://raw.githubusercontent.com/Open-Technology-Foundation/vrecord/main/install.sh | bash\n\n# Or for user-only installation (no sudo required)\ncurl -fsSL https://raw.githubusercontent.com/Open-Technology-Foundation/vrecord/main/install.sh | bash -s -- --user\n\n# Local installation from downloaded/cloned directory\n./install.sh --dev\n```\n\n## Features\n\n- **Pause/resume** via SIGSTOP/SIGCONT signals\n- **Continue recordings** - append to existing WAV files\n- **Automatic MP3** conversion (libmp3lame)\n- **Transcription** integration (optional)\n- **Beep notifications** - periodic audio reminder while recording\n- **Background operation** - recordings persist after terminal closes\n- **Secure** - input validation prevents injection and path traversal\n- **Concurrent protection** - flock-based locking prevents conflicts\n\n## Quick Start\n\n```bash\n# Start a new recording\nvrecord start\n\n# Stop recording and save\nvrecord stop\n\n# Stop and transcribe (-t, if transcribe tool is installed)\nvrecord stop -t\n\n# Your recording is saved in ~/Recordings/\n```\n\n## vrecord-loop - Quick Recording Loop\n\n`vrecord-loop` is a companion script for rapid voice recordings with automatic transcription. It provides an interactive loop: record → stop → display transcription → repeat.\n\n### Usage\n\n```bash\n# Start interactive recording loop\nvrecord-loop\n\n# With custom filename prefix\nvrecord-loop meeting-notes\n\n# Quiet mode (suppress non-error output)\nvrecord-loop -q\n```\n\n### How It Works\n\n1. Recording starts automatically with transcription enabled\n2. Press any key to stop recording\n3. Recording is converted to MP3 and transcribed\n4. Transcription is displayed\n5. Press Enter to start next recording, or 'q' to quit\n\n### Options\n\n| Option | Description |\n|--------|-------------|\n| `-v, --verbose` | Enable verbose output (default) |\n| `-q, --quiet` | Suppress non-error output |\n| `-h, --help` | Show help |\n| `-V, --version` | Show version |\n\n**Requires**: vrecord, transcribe command in PATH\n\n## Installation\n\n### Automatic Installation (Recommended)\n\nUse the install script for automatic setup with bash completion:\n\n```bash\n# System-wide installation (will prompt for sudo password)\n./install.sh\n\n# User-only installation (no sudo needed)\n./install.sh --user\n\n# Development installation (creates symlinks for testing)\n./install.sh --dev\n\n# See all options\n./install.sh --help\n```\n\nThe installer will:\n- Check for required dependencies\n- Install vrecord and bash completion\n- Create configuration directory\n- Generate an uninstall script\n\n### Manual Installation\n\n1. Ensure you have the required dependencies:\n   ```bash\n   sudo apt-get install ffmpeg pulseaudio\n   # Optional: for compressed logs\n   sudo apt-get install gzip\n   ```\n\n2. Make the script executable:\n   ```bash\n   chmod +x vrecord\n   ```\n\n3. Copy to your PATH:\n   ```bash\n   # System-wide\n   sudo cp vrecord vrecord-loop /usr/local/bin/\n\n   # Or user-only\n   mkdir -p ~/.local/bin\n   cp vrecord vrecord-loop ~/.local/bin/\n   ```\n\n4. Enable bash completion:\n   ```bash\n   # System-wide\n   sudo cp .bash_completion /etc/bash_completion.d/vrecord\n\n   # Or user-only\n   mkdir -p ~/.local/share/bash-completion/completions\n   cp .bash_completion ~/.local/share/bash-completion/completions/vrecord\n   ```\n\n5. (Optional) Configure settings:\n   ```bash\n   # Copy sample config and customize\n   mkdir -p ~/.vrecord\n   cp config.sample ~/.vrecord/config\n   nano ~/.vrecord/config\n   ```\n\n### Uninstallation\n\nIf installed with the installer:\n```bash\n~/.vrecord/uninstall.sh\n```\n\nOr manually remove:\n```bash\nsudo rm -f /usr/local/bin/vrecord /usr/local/bin/vrecord-loop\nsudo rm -f /etc/bash_completion.d/vrecord\nrm -rf ~/.vrecord  # Optional: remove config\n```\n\n## Usage Examples\n\n### Basic Recording\n\n```bash\n# Start recording with default name (voice_recording_TIMESTAMP.wav)\nvrecord start\n\n# Start recording with custom prefix\nvrecord start interview\n# Creates: interview_20240115_143022.wav\n\n# Start with transcription enabled\nvrecord start -t meeting\n\n# Stop recording (automatically converts to MP3)\nvrecord stop\n\n# Stop and transcribe\nvrecord stop -t\n```\n\n### Pause and Resume\n\n```bash\n# Pause the current recording\nvrecord pause\n\n# Resume recording\nvrecord resume\n```\n\n### Continue Previous Recordings\n\n```bash\n# Continue the most recent recording\nvrecord start -c\n\n# Resume a specific recording file\nvrecord start -r voice_recording_20240115_143022.wav\n\n# Start recording with transcription enabled\nvrecord start -t podcast\n```\n\n**Note**: Filename prefixes must contain only alphanumeric characters, dots, underscores, and hyphens for security reasons.\n\n### Other Commands\n\n```bash\n# Check recording status\nvrecord status\n\n# List all recordings\nvrecord list\n\n# List all files (not just WAV)\nvrecord list --all\n\n# Skip MP3 conversion\nvrecord -n start\nvrecord stop  # Won't create MP3\n\n# Disable beep notifications\nvrecord -b start\n# Or: vrecord --no-beep start\n\n# Enable transcription globally\nvrecord start -t    # Start with transcription\nvrecord stop        # Will transcribe if started with -t\nvrecord stop -t     # Or, you can decide to transcribe when stopping\nvrecord -n start -t # No MP3 conversion but transcribe enabled (won't transcribe without MP3. So don't do that.)\n\n# Show version\nvrecord -V\n```\n\n## Command Reference\n\n### Commands\n\n| Command | Description |\n|---------|-------------|\n| `start [PREFIX]` | Start new recording (default prefix: voice_recording) |\n| `start -c` | Continue the most recent recording |\n| `start -r FILE` | Resume a specific WAV file |\n| `pause` | Pause active recording (SIGSTOP) |\n| `resume` | Resume paused recording (SIGCONT) |\n| `stop` | Stop recording, create MP3 |\n| `status` | Show recording state and file info |\n| `list [--all]` | List WAV files (or all files with --all) |\n\n### Start Options\n\n| Option | Description |\n|--------|-------------|\n| `-c, --continue-last` | Append to the most recent WAV file |\n| `-r, --resume FILE` | Append to a specific WAV file |\n| `-t, --transcribe` | Transcribe after MP3 conversion |\n\n### Stop Options\n\n| Option | Description |\n|--------|-------------|\n| `-t, --transcribe` | Transcribe the MP3 file |\n\n### Global Options\n\n| Option | Description |\n|--------|-------------|\n| `-n, --no-mp3` | Skip MP3 conversion |\n| `-b, --no-beep` | Disable periodic beep reminders |\n| `-v, --verbose` | Increase output verbosity |\n| `-q, --quiet` | Suppress non-error output |\n| `-h, --help` | Show help |\n| `-V, --version` | Show version |\n\n## Default File Locations\n\n- **Recordings**: `~/Recordings/`\n- **State files**: `~/.vrecord/`\n- **Temporary files**: `/tmp/vrecord.XXXXXX/`\n- **System beep file**: `/usr/local/share/vrecord/beep.mp3` (system installation)\n- **User beep file**: `~/.vrecord/beep.mp3` (user installation)\n\n## Configuration\n\nConfiguration precedence (highest to lowest):\n\n1. **Environment variables** (`VRECORD_*` prefix)\n2. **User config**: `~/.vrecord/config`\n3. **System config**: `/etc/vrecord/config`\n4. **Built-in defaults**\n\n### Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `VRECORD_RECORDING_DIR` | Where WAV/MP3 files are saved | `~/Recordings` |\n| `VRECORD_STATE_DIR` | Persistent state directory | `~/.vrecord` |\n| `VRECORD_DEFAULT_PREFIX` | Filename prefix when none specified | `voice_recording` |\n| `VRECORD_MP3_BITRATE` | libmp3lame bitrate | `192k` |\n\nConfig files are bash scripts that set variables directly (without the `VRECORD_` prefix).\n\n### Beep Notifications\n\nConfigure beep notifications in your config file:\n```bash\nBEEP_ENABLED=1        # Enable beeps (0 to disable)\nBEEP_INTERVAL=60      # Seconds between beeps\nBEEP_FILE=\"$STATE_DIR/beep.mp3\"  # Custom beep sound\n```\n\nThe installer includes a default beep sound. You can replace it with any tiny MP3 file that emits a non-distracting pip while recording is in progress.\n\n### Transcription\n\nIf you have a `transcribe` command available in your PATH, you can enable automatic transcription:\n```bash\n# Enable transcription when starting\nvrecord start -t\n\n# Or enable when stopping\nvrecord stop -t\n```\n\nThe transcription will run after the MP3 file is created. The `transcribe` command will be called with the MP3 filename as its argument.\n\n**Note**: If you have OPENAI_API_KEY, you can use the transcription feature.  Install the transcribe tool from:\n[https://github.com/Open-Technology-Foundation/transcribe](https://github.com/Open-Technology-Foundation/transcribe).  Use will require OPENAI_API_KEY.\n\n### Audio Settings\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `AUDIO_FORMAT` | WAV codec | `pcm_s16le` (16-bit PCM) |\n| `SAMPLE_RATE` | Sample rate (Hz) | `44100` |\n| `CHANNELS` | Mono (1) or stereo (2) | `2` |\n| `MIN_DISK_SPACE_MB` | Minimum free space to start | `100` |\n| `LOG_MAX_SIZE_MB` | Rotate logs when exceeded | `10` |\n| `LOG_MAX_FILES` | Rotated log files to keep | `5` |\n\nSee `config.sample` for a complete example.\n\n## How It Works\n\n1. **Recording**: FFmpeg captures audio from PulseAudio default input\n2. **Pause/Resume**: SIGSTOP suspends ffmpeg; SIGCONT resumes it\n3. **Continue/Resume**: New audio records to segment files, merged on stop using ffmpeg concat demuxer\n4. **State**: Session data stored in `/tmp/vrecord.XXXXXX/` (ffmpeg.pid, state, segments/)\n5. **Locking**: flock(1) prevents concurrent instances; falls back to atomic rename\n6. **Stop sequence**: SIGCONT (if paused) → SIGTERM → wait → SIGKILL (timeout)\n7. **Conversion**: WAV → MP3 via libmp3lame at configured bitrate\n\n## Tips\n\n- Recordings continue in the background even if you close the terminal\n- Use `vrecord status` to check if a recording is active\n- The script prevents multiple simultaneous recordings\n- Original WAV files are preserved alongside MP3 versions\n- Use `Ctrl+C` safely - recordings won't be lost\n\n## Troubleshooting\n\n### No sound recorded\n- Check your microphone is connected and working\n- Ensure PulseAudio is running: `pactl info`\n- Check default input device: `pactl list sources`\n\n### FFmpeg errors\n- Verify FFmpeg has PulseAudio support: `ffmpeg -devices 2\u003e\u00261 | grep pulse`\n- Check FFmpeg logs in `/tmp/vrecord.*/ffmpeg.log`\n\n### Permission errors\n- Ensure `~/Recordings/` directory is writable\n- Check disk space: `df -h ~/Recordings`\n\n### \"Another instance is running\" error\n- Only one recording can be active at a time\n- Check status: `vrecord status`\n- If no recording is active but error persists, a stale lock may exist\n- The script will automatically clean stale locks on next run\n\n## Security\n\nvrecord implements several security measures:\n\n- **Input Validation**: All filenames and paths are validated to prevent command injection\n- **Path Restrictions**: Recording files are restricted to the configured recording directory\n- **Safe Characters**: Only alphanumeric characters, dots, underscores, and hyphens allowed in filenames\n- **Atomic Locking**: Uses kernel-level file locking to prevent race conditions\n- **No Shell Expansion**: User inputs are never passed directly to shell commands\n\n## Requirements\n\n- **Bash 5.2+** (uses `inherit_errexit`, `extglob`, `nullglob`)\n- **FFmpeg** with PulseAudio support (`ffmpeg -devices | grep pulse`)\n- **PulseAudio** (`pactl`)\n- **Optional**: mediainfo (file info), gzip (log compression), transcribe (transcription)\n\n## Development\n\n### Testing\n\n```bash\n./run_tests.sh                           # Full test suite\n./tests/test_vrecord.sh basic_commands   # Specific suite\n./tests/test_vrecord.sh recording_basic\n./tests/test_vrecord.sh pause_resume\n```\n\n### Code Standards\n\n- `set -euo pipefail` with `inherit_errexit`\n- 2-space indentation, ShellCheck compliant\n- Follows [BCS (Bash Coding Standard)](https://github.com/Open-Technology-Foundation/bash-coding-standard)\n\n## License\n\nGPL-3.0-or-later - Copyright (C) 2024-2025 Open Technology Foundation\n\n## Links\n\n- **Repository**: [github.com/Open-Technology-Foundation/vrecord](https://github.com/Open-Technology-Foundation/vrecord)\n- **Issues**: [github.com/Open-Technology-Foundation/vrecord/issues](https://github.com/Open-Technology-Foundation/vrecord/issues)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopen-technology-foundation%2Fvrecord","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopen-technology-foundation%2Fvrecord","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopen-technology-foundation%2Fvrecord/lists"}