{"id":30855516,"url":"https://github.com/cryptofyre/meiko","last_synced_at":"2025-09-07T11:07:51.461Z","repository":{"id":297870078,"uuid":"998153251","full_name":"cryptofyre/Meiko","owner":"cryptofyre","description":"Meiko is a unified Go application that integrates SDRTrunk and audio transcription services","archived":false,"fork":false,"pushed_at":"2025-06-08T02:21:52.000Z","size":1008,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-06-08T02:43:59.898Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cryptofyre.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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},"funding":{"ko_fi":"cryptofyre"}},"created_at":"2025-06-08T01:20:34.000Z","updated_at":"2025-06-08T02:21:55.000Z","dependencies_parsed_at":"2025-06-08T02:44:11.630Z","dependency_job_id":"1346f5c0-cf85-4172-ad4a-cfcb28b9e672","html_url":"https://github.com/cryptofyre/Meiko","commit_stats":null,"previous_names":["cryptofyre/meiko"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/cryptofyre/Meiko","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cryptofyre%2FMeiko","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cryptofyre%2FMeiko/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cryptofyre%2FMeiko/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cryptofyre%2FMeiko/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cryptofyre","download_url":"https://codeload.github.com/cryptofyre/Meiko/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cryptofyre%2FMeiko/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274026718,"owners_count":25209740,"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-09-07T02:00:09.463Z","response_time":67,"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":[],"created_at":"2025-09-07T11:07:47.565Z","updated_at":"2025-09-07T11:07:51.444Z","avatar_url":"https://github.com/cryptofyre.png","language":"Go","funding_links":["https://ko-fi.com/cryptofyre"],"categories":[],"sub_categories":[],"readme":"# Meiko - Unified SDRTrunk \u0026 Transcription System\n\n🎤 **Meiko** is a unified Go application that integrates SDRTrunk and audio transcription services. It provides a local-first, robust, and user-friendly experience for monitoring and transcribing radio communications.\n\n## Features\n\n### Core Functionality\n- **SDRTrunk Process Management**: Launches and monitors SDRTrunk as a child process\n- **File System Monitoring**: Watches for new audio recordings from SDRTrunk\n- **Dual Transcription Modes**: \n  - Local transcription using faster-whisper\n  - Remote transcription via API endpoints\n- **Discord Integration**: Real-time notifications and system status updates\n- **Database Storage**: SQLite database for call records and transcriptions\n- **System Monitoring**: Health checks and performance monitoring\n- **Pre-flight Validation**: Comprehensive system checks before startup\n\n### Enhanced Features\n- **Colored Console Logging**: Beautiful, informative console output with spinners\n- **Graceful Shutdown**: Proper cleanup and shutdown handling\n- **Configuration Validation**: Comprehensive config file validation\n- **Error Recovery**: Robust error handling and recovery mechanisms\n- **Performance Monitoring**: CPU, memory, and disk usage tracking\n\n## 🚀 Performance Features\n\n### Optimized Single-Process Architecture\nMeiko uses a single-process architecture optimized for SDR monitoring workloads. While pre-forking could improve web performance, it conflicts with SDRTrunk's single-instance requirement.\n\n**Why Single-Process:**\n- **SDRTrunk Compatibility** - Prevents multiple SDRTrunk instances competing for audio hardware\n- **Resource Efficiency** - Avoids duplicate file watchers and database connections\n- **Deterministic Behavior** - Ensures consistent audio processing and transcription\n- **Simplified Debugging** - Single process makes troubleshooting easier\n\n**Performance Optimizations:**\n- Memory usage reduction enabled\n- Optimized connection handling (256K max concurrent)\n- Smart idle timeout management (60s)\n- Keep-alive connections for faster response times\n- Efficient static file serving with compression\n\n**Future Scaling Options:**\n- **Reverse Proxy** - Use nginx/Apache for static file serving and load balancing\n- **CDN Integration** - Serve static assets from content delivery networks  \n- **Database Optimization** - Connection pooling and query optimization\n- **Caching Layer** - Redis/Memcached for frequently accessed data\n- **Microservices** - Separate web dashboard from SDR processing if needed\n\n## Installation\n\n### Prerequisites\n\n1. **Go 1.21 or later**\n2. **Java Runtime Environment** (for SDRTrunk)\n3. **Python 3.8+** (for local transcription)\n4. **SDRTrunk** application\n5. **faster-whisper** (for local transcription): `pip install faster-whisper`\n\n### Build from Source\n\n```bash\ngit clone https://github.com/your-username/Meiko.git\ncd Meiko\ngo mod tidy\ngo build -o meiko\n```\n\n## Configuration\n\nCopy and customize the configuration file:\n\n```bash\ncp config.yaml config-local.yaml\n```\n\n### Key Configuration Sections\n\n#### SDRTrunk Settings\n```yaml\nsdrtrunk:\n  # For JAR distribution\n  path: \"/path/to/sdrtrunk.jar\"\n  java_path: \"java\"\n  jvm_args: [\"-Xmx2g\", \"-Xms512m\"]\n  \n  # OR for Linux binary distribution\n  path: \"/path/to/sdr-trunk\"\n  # java_path and jvm_args are ignored for binaries\n  \n  audio_output_dir: \"/path/to/recordings\"\n```\n\n#### Transcription Settings\n```yaml\ntranscription:\n  mode: \"local\"  # or \"remote\"\n  local:\n    whisper_script: \"./fasterWhisper.py\"\n    python_path: \"python\"\n    model_size: \"tiny\"\n    device: \"cpu\"\n    language: \"en\"\n```\n\n#### Discord Integration\n```yaml\ndiscord:\n  token: \"YOUR_DISCORD_BOT_TOKEN\"\n  channel_id: \"YOUR_CHANNEL_ID\"\n  notifications:\n    startup: true\n    shutdown: true\n    errors: true\n    transcriptions: true\n```\n\n## Usage\n\n### Basic Usage\n\n1. **Configure the application**:\n   ```bash\n   # Edit config.yaml with your settings\n   nano config.yaml\n   ```\n\n2. **Run Meiko**:\n   ```bash\n   ./meiko\n   ```\n\n### Command Line Options\n\n```bash\n# Use custom config file\n./meiko -config custom-config.yaml\n\n# Enable debug logging\n./meiko -debug\n\n# Show version\n./meiko -version\n```\n\n### Pre-flight Checks\n\nMeiko automatically runs pre-flight checks on startup:\n- ✅ SDRTrunk path validation\n- ✅ Java runtime availability\n- ✅ Audio output directory permissions\n- ✅ Transcription service configuration\n- ✅ Database connectivity\n- ✅ USB device detection (optional)\n\n## Architecture\n\n### Component Overview\n\n```\n┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐\n│   SDRTrunk      │    │   File Watcher   │    │  Transcription  │\n│   Manager       │───▶│                  │───▶│   Service       │\n└─────────────────┘    └──────────────────┘    └─────────────────┘\n         │                       │                       │\n         ▼                       ▼                       ▼\n┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐\n│   Process       │    │   Call           │    │   Database      │\n│   Monitor       │    │   Processor      │    │                 │\n└─────────────────┘    └──────────────────┘    └─────────────────┘\n         │                       │                       │\n         ▼                       ▼                       ▼\n┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐\n│   Discord       │    │   System         │    │   Logger        │\n│   Client        │    │   Monitor        │    │                 │\n└─────────────────┘    └──────────────────┘    └─────────────────┘\n```\n\n### Data Flow\n\n1. **SDRTrunk** generates audio recordings\n2. **File Watcher** detects new files\n3. **Call Processor** extracts metadata and queues for transcription\n4. **Transcription Service** processes audio (local or remote)\n5. **Database** stores call records and transcriptions\n6. **Discord Client** sends notifications\n7. **System Monitor** tracks performance and health\n\n## Transcription Modes\n\n### Local Mode (faster-whisper)\n\nUses the included `fasterWhisper.py` script with the faster-whisper library:\n\n```yaml\ntranscription:\n  mode: \"local\"\n  local:\n    whisper_script: \"./fasterWhisper.py\"\n    model_size: \"tiny\"  # tiny, base, small, medium, large\n    device: \"cpu\"       # cpu, cuda\n```\n\n**Advantages:**\n- No internet required\n- Lower latency\n- Privacy-focused\n- No API costs\n\n### Remote Mode\n\nSends audio files to a remote transcription API:\n\n```yaml\ntranscription:\n  mode: \"remote\"\n  remote:\n    endpoint: \"https://your-api.com/transcribe\"\n    api_key: \"your-api-key\"\n    timeout: 30\n```\n\n**Advantages:**\n- More powerful models\n- No local compute requirements\n- Centralized processing\n\n## Discord Integration\n\n### Bot Setup\n\n1. Create a Discord application at https://discord.com/developers/applications\n2. Create a bot and copy the token\n3. Invite the bot to your server with appropriate permissions\n4. Configure the bot token and channel ID in `config.yaml`\n\n### Notification Types\n\n- 🚀 **Startup/Shutdown**: Application lifecycle events\n- ❌ **Errors**: Critical errors and failures\n- 📞 **Transcriptions**: New call transcriptions\n- 📊 **System Health**: Performance alerts and warnings\n\n## Database Schema\n\n### Calls Table\n```sql\nCREATE TABLE calls (\n    id INTEGER PRIMARY KEY AUTOINCREMENT,\n    filename TEXT NOT NULL,\n    filepath TEXT NOT NULL UNIQUE,\n    talkgroup_id TEXT,\n    from_id TEXT,\n    to_id TEXT,\n    unixtime INTEGER,\n    duration REAL,\n    transcription TEXT,\n    processed BOOLEAN DEFAULT FALSE,\n    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP\n);\n```\n\n## Monitoring and Logging\n\n### Log Levels\n- **DEBUG**: Detailed debugging information\n- **INFO**: General information messages\n- **WARN**: Warning messages\n- **ERROR**: Error messages\n\n### System Monitoring\n- CPU usage monitoring\n- Memory usage tracking\n- Disk space monitoring\n- Process health checks\n- Automatic alerting\n\n## Troubleshooting\n\n### Common Issues\n\n#### SDRTrunk Won't Start\n```bash\n# Check Java installation\njava -version\n\n# Verify SDRTrunk path\nls -la /path/to/sdrtrunk.jar\n\n# Check permissions\nchmod +x /path/to/sdrtrunk.jar\n```\n\n#### Transcription Failures\n```bash\n# Test Python and faster-whisper\npython -c \"import faster_whisper; print('OK')\"\n\n# Test whisper script directly\npython ./fasterWhisper.py test-audio.mp3\n```\n\n#### Discord Connection Issues\n- Verify bot token is correct\n- Check bot permissions in Discord server\n- Ensure channel ID is valid\n\n### Debug Mode\n\nEnable debug logging for detailed troubleshooting:\n\n```yaml\nlogging:\n  level: \"DEBUG\"\n  colors: true\n  timestamps: true\n```\n\n## Performance Tuning\n\n### Transcription Performance\n- Use GPU acceleration: `device: \"cuda\"`\n- Adjust model size: `tiny` (fastest) to `large` (most accurate)\n- Tune batch processing: `batch_size: 5`\n\n### System Performance\n- Adjust file monitoring interval: `poll_interval: 1000`\n- Configure database connection pool: `max_open_conns: 10`\n- Set appropriate JVM memory: `jvm_args: [\"-Xmx4g\"]`\n\n## Development\n\n### Project Structure\n```\nMeiko/\n├── main.go                 # Application entry point\n├── config.yaml            # Configuration file\n├── fasterWhisper.py       # Transcription script\n├── internal/              # Internal packages\n│   ├── config/           # Configuration management\n│   ├── database/         # Database operations\n│   ├── discord/          # Discord integration\n│   ├── logger/           # Logging system\n│   ├── monitoring/       # System monitoring\n│   ├── preflight/        # Pre-flight checks\n│   ├── processor/        # Call processing\n│   ├── sdrtrunk/         # SDRTrunk management\n│   ├── transcription/    # Transcription services\n│   └── watcher/          # File system monitoring\n└── references/           # Reference implementations\n```\n\n### Building\n\n```bash\n# Development build\ngo build -o meiko\n\n# Production build with optimizations\ngo build -ldflags \"-s -w\" -o meiko\n\n# Cross-compilation for Linux\nGOOS=linux GOARCH=amd64 go build -o meiko-linux\n\n# Cross-compilation for Windows\nGOOS=windows GOARCH=amd64 go build -o meiko.exe\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Submit a pull request\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Acknowledgments\n\n- **SDRTrunk**: The excellent SDR trunking application\n- **faster-whisper**: High-performance speech recognition\n- **Original Projects**: Swimtrunks and SdrTrunk-Transcriber for inspiration\n\n## Support\n\n- 📖 **Documentation**: Check this README and inline code comments\n- 🐛 **Issues**: Report bugs via GitHub Issues\n- 💬 **Discussions**: Use GitHub Discussions for questions\n\n---\n\n**Made with ❤️ for the radio monitoring community**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcryptofyre%2Fmeiko","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcryptofyre%2Fmeiko","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcryptofyre%2Fmeiko/lists"}