{"id":28444537,"url":"https://github.com/nnanto/transcriber","last_synced_at":"2025-10-28T23:09:59.514Z","repository":{"id":296121069,"uuid":"992355490","full_name":"nnanto/transcriber","owner":"nnanto","description":"Audio transcription tool powered by whisper.cpp, designed for real-time transcription. NO API/CLOUD","archived":false,"fork":false,"pushed_at":"2025-05-29T05:49:45.000Z","size":41,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-29T18:51:04.242Z","etag":null,"topics":["audio-transcription","whisper-cpp"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nnanto.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}},"created_at":"2025-05-29T02:54:44.000Z","updated_at":"2025-06-03T05:01:10.000Z","dependencies_parsed_at":"2025-05-29T03:43:50.982Z","dependency_job_id":"4d9aea9d-9edd-43cd-9ec7-098448ffdb5f","html_url":"https://github.com/nnanto/transcriber","commit_stats":null,"previous_names":["nnanto/transcriber"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/nnanto/transcriber","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nnanto%2Ftranscriber","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nnanto%2Ftranscriber/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nnanto%2Ftranscriber/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nnanto%2Ftranscriber/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nnanto","download_url":"https://codeload.github.com/nnanto/transcriber/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nnanto%2Ftranscriber/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":281527389,"owners_count":26516850,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-28T02:00:06.022Z","response_time":60,"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":["audio-transcription","whisper-cpp"],"created_at":"2025-06-06T09:09:40.775Z","updated_at":"2025-10-28T23:09:59.486Z","avatar_url":"https://github.com/nnanto.png","language":"Go","readme":"# 🎙️ Transcriber\n\n\u003e CLI for audio transcription tool powered by whisper.cpp, designed for real-time transcription.\n\n[![GitHub Stars](https://img.shields.io/github/stars/nnanto/transcriber.svg?style=social)](https://github.com/nnanto/transcriber/stargazers)\n\n[![Go Version](https://img.shields.io/badge/Go-1.19+-blue.svg)](https://golang.org)\n[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n[![Platform](https://img.shields.io/badge/Platform-Linux%20%7C%20macOS%20%7C%20Windows-lightgrey.svg)]()\n\n## ✨ Features\n\n- 🎯 **Real-time transcription** - Record and transcribe audio on the fly\n- 🚀 **Cross-platform** - Works on Linux, macOS, and Windows\n- ⚙️ **Configurable** - Flexible configuration options\n- 🔧 **Multiple models** - Support for various Whisper model sizes\n- 💻 **CLI-friendly** - Easy-to-use command-line interface\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- Install `whisper-cli`\n  - Mac OS: `brew install whisper-cpp`\n  - Other OS: Follow the [whisper.cpp installation guide](https://github.com/ggml-org/whisper.cpp?tab=readme-ov-file#quick-start)\n- Install `ffmpeg` for audio recording\n  - Mac OS: `brew install ffmpeg`\n  - Linux: Use your package manager (e.g., `apt install ffmpeg`)\n  - Windows: Download from [FFmpeg official site](https://ffmpeg.org/download.html)\n- Audio recording capabilities (microphone)\n- At least 4GB RAM (recommended for larger models)\n\n### Installation\n\n#### Option 1: Download pre-built binary (Recommended)\nDownload the latest release for your platform from [GitHub Releases](https://github.com/nnanto/transcriber/releases):\n\n**One-line MacOS installation**\n```bash\nsh -c \"$(curl -fsSL https://raw.githubusercontent.com/nnanto/transcriber/main/scripts/install-macos.sh)\"\n```\n\n**Linux/macOS:**\n```bash\n# Download and install \ncurl -L https://github.com/nnanto/transcriber/releases/download/latest/transcriber-linux-amd64.tar.gz | tar -xz\nsudo mv transcriber-* /usr/local/bin/transcriber\n\n# Or for macOS\ncurl -L https://github.com/nnanto/transcriber/releases/download/latest/transcriber-darwin-amd64.tar.gz | tar -xz\nsudo mv transcriber-* /usr/local/bin/transcriber\n\n# Make executable\nchmod +x /usr/local/bin/transcriber\n```\n\n**Windows:**\n1. Download `transcriber-windows-amd64.zip` from [releases page](https://github.com/nnanto/transcriber/releases)\n2. Extract the ZIP file\n3. Add the extracted folder to your PATH or move `transcriber.exe` to a folder in your PATH\n\n**Verify installation:**\n```bash\ntranscriber version\n```\n\n#### Option 2: Install from source\n```bash\ngit clone https://github.com/nnanto/transcriber.git\ncd transcriber\nmake install\n```\n\n#### Option 3: Build locally\n```bash\ngit clone https://github.com/nnanto/transcriber.git\ncd transcriber\nmake build\n```\n\n### First Run\n\n1. **Install whisper-cli** if not already done.\n   See [prerequisites](#prerequisites)\n\n2. **Download a Whisper model** (required on first use):\n```bash\ntranscriber download-model\n```\nYou can specify custom model using `--model` option. Available models are found in the [whisper.cpp HF models](https://huggingface.co/ggerganov/whisper.cpp/tree/main)\n\nYou can also specify a custom model path in the configuration file.\n\n3. **Start transcribing**:\n```bash\ntranscriber run --output ./transcriptions\n```\n\n4. **Check your configuration**:\n```bash\ntranscriber config\n```\n\n## 📖 Usage Guide\n\n### Commands Overview\n\n| Command | Description | Example |\n|---------|-------------|---------|\n| `run` | Record and transcribe in real-time | `transcriber run --duration 2m` |\n| `process` | Process existing audio files | `transcriber process --input ./audio` |\n| `config` | Show current configuration | `transcriber config` |\n| `download` | Download Whisper models | `transcriber download-model --model large` |\n| `stop` | Stop all running processes | `transcriber stop` |\n| `version` | Show version info | `transcriber version` |\n\n### Real-time Transcription\n\nStart recording and transcribing immediately:\n\n```bash\n# Record for 30 minutes (default)\ntranscriber run\n\n# Record for specific duration\ntranscriber run --duration 5m --output ./my-transcriptions\n\n# Custom configuration\ntranscriber run --config ./custom-config --duration 1h\n```\n\n### Model Management\n\nDownload and manage Whisper models:\n\n```bash\n# Download specific model\ntranscriber download-model --model ggml-large-v3-turbo-q5_0\n```\n\nAvailable models are found in the [whisper.cpp HF models](https://huggingface.co/ggerganov/whisper.cpp/tree/main)\n\n\n## ⚙️ Configuration\n\nThe configuration file is automatically created at `~/.transcriber/config.json`:\n\n```json\n{\n  \"model_path\": \"~/.transcriber/models/ggml-large-v3-turbo-q5_0.bin\",\n  \"language\": \"English\",\n  \"temp_dir\": \"/tmp/transcriber\",\n  \"output_format\": \"txt\",\n  \"whisper_cmd\": \"whisper-cli\",\n  \"recording_cmd\": \"ffmpeg\",\n  \"chunk_duration_in_secs\": 30,\n  \"min_required_unique_word_count\": 5\n}\n```\n\n### Configuration Options\n\n- **model_path**: Path to the Whisper model file\n- **language**: Language for transcription (e.g., \"English\", \"Spanish\", \"auto\")\n- **temp_dir**: Directory for temporary audio files during processing\n- **output_format**: Output format (`txt`, `json`)\n- **whisper_cmd**: Command to use for Whisper transcription (default: \"whisper-cli\")\n- **recording_cmd**: Command to use for audio recording (default: \"ffmpeg\")\n- **chunk_duration_in_secs**: Duration in seconds for each audio chunk during real-time transcription (default: 30)\n- **min_required_unique_word_count**: Minimum number of unique words required to process a chunk (default: 5)\n\n## 🛠️ Development Guide\n\n### Project Structure\n\n```\ntranscriber/\n├── cmd.go              # CLI command handling\n├── main.go             # Application entry point\n├── transcriber.go      # Core transcription logic\n├── config.go           # Configuration management\n├── audio.go            # Audio recording/processing\n├── models.go           # Model download/management\n├── Makefile            # Build automation\n└── README.md           # This file\n```\n\n### Building from Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/nnanto/transcriber.git\ncd transcriber\n\n# Install dependencies\ngo mod download\n\n# Build for development (with race detection)\nmake dev\n\n# Build for production\nmake build\n\n# Run tests\nmake test\n\n# Build for all platforms\nmake release-local\n```\n\n## 🐛 Troubleshooting\n\n### Common Issues\n\n#### \"Model not found\" error\n```bash\n# Download the required model first\ntranscriber download-model [--model ggml-base]\n```\n\n#### Permission denied on macOS/Linux\n```bash\n# Make sure the binary is executable\nchmod +x transcriber\n\n# Or install system-wide\nmake install\n```\n\n#### High CPU usage\n- Try using a smaller model (`ggml-tiny` or `ggml-base`)\n- Reduce recording quality in config\n- Limit recording duration\n\n#### Audio recording issues\n- Check microphone permissions\n- Verify audio device availability\n- Test with shorter durations first\n\n### Getting Help\n\n- Check the [Issues](https://github.com/nnanto/transcriber/issues) page\n- Review configuration with `transcriber config`\n- Enable verbose logging in development builds\n\n## 📋 System Requirements\n\n### Minimum Requirements\n- **OS**: Linux, macOS 10.14+, Windows 10+\n- **RAM**: 2GB (4GB recommended)\n- **Storage**: 1GB free space\n- **Go**: 1.19+ (for building from source)\n\n### Model Size Requirements\n- **tiny**: ~39MB, ~125MB RAM\n- **base**: ~142MB, ~210MB RAM  \n- **small**: ~466MB, ~550MB RAM\n- **medium**: ~1.5GB, ~2GB RAM\n- **large**: ~2.9GB, ~4GB RAM\n\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n\u003cdiv align=\"center\"\u003e\nMade with ❤️ by the Transcriber team\n\u003c/div\u003e\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnnanto%2Ftranscriber","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnnanto%2Ftranscriber","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnnanto%2Ftranscriber/lists"}