{"id":26349590,"url":"https://github.com/willibrandon/lofibeats","last_synced_at":"2025-07-31T04:05:42.986Z","repository":{"id":277676852,"uuid":"933175530","full_name":"willibrandon/LofiBeats","owner":"willibrandon","description":"A cross-platform .NET application that generates and plays lofi beats with real-time audio effects, featuring an interactive CLI, REST API service, WebSockets support, plugin-based architecture, and telemetry.","archived":false,"fork":false,"pushed_at":"2025-02-22T23:45:27.000Z","size":524,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-23T00:36:00.959Z","etag":null,"topics":["audio","cli","cross-platform","dotnet","dsp","effects","lofi","music","plugin-architecture","rest-api","telemetry","websockets"],"latest_commit_sha":null,"homepage":"","language":"C#","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/willibrandon.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","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}},"created_at":"2025-02-15T10:33:48.000Z","updated_at":"2025-02-22T23:45:31.000Z","dependencies_parsed_at":"2025-02-15T11:28:35.333Z","dependency_job_id":"99f1f98b-cfd0-4844-aadb-7f9e21a5bcc7","html_url":"https://github.com/willibrandon/LofiBeats","commit_stats":null,"previous_names":["willibrandon/lofibeats"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/willibrandon%2FLofiBeats","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/willibrandon%2FLofiBeats/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/willibrandon%2FLofiBeats/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/willibrandon%2FLofiBeats/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/willibrandon","download_url":"https://codeload.github.com/willibrandon/LofiBeats/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243847368,"owners_count":20357362,"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","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","cli","cross-platform","dotnet","dsp","effects","lofi","music","plugin-architecture","rest-api","telemetry","websockets"],"created_at":"2025-03-16T09:18:53.398Z","updated_at":"2025-03-16T09:18:53.885Z","avatar_url":"https://github.com/willibrandon.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# LofiBeats\n\nA cross-platform command-line tool and service for generating and playing lofi beats with real-time effects.\n\n## Features\n\n- Generate lofi beats with different styles (basic, jazzy, chillhop, hiphop)\n  - Configurable musical key (C, F#, Bb, etc.)\n  - Automatic chord transposition\n  - Enharmonic equivalent support\n- Real-time audio effects:\n  - Tape Stop (gradually slow down the audio like a tape machine powering off)\n  - Tape Flutter (adds wow/flutter pitch drift and tape hiss for vintage vibes)\n  - Vinyl (adds vinyl record crackle and noise for that authentic feel)\n  - Reverb (adds space and atmosphere to create depth)\n  - Low Pass Filter (reduces high frequencies for that warm, mellow sound)\n- Plugin system for custom effects\n- Advanced Drum Synthesis:\n  - Multi-stage envelopes for realistic drum sounds\n  - Velocity and timing humanization\n  - Customizable synthesis parameters\n- Smooth transitions between patterns:\n  - Crossfade between styles (0.1s to 10s duration)\n  - Bar-synchronized transitions\n  - Schedule future transitions\n- User Sample Support:\n  - Register your own drum samples\n  - Support for velocity layers\n  - Automatic sample management\n  - Preloading option for optimal performance\n- Preset Management:\n  - Save current style, volume, and effects to a preset file\n  - Load presets to quickly restore your favorite configurations\n  - JSON-based preset format for easy sharing and editing\n- Schedule Management:\n  - Schedule playback and stop actions with delays\n  - List all pending scheduled actions\n  - Cancel specific scheduled actions by ID\n  - Real-time progress tracking for scheduled actions\n- Interactive mode for live control\n- RESTful API service for remote control\n- WebSocket connections for real-time control\n- Cross-platform support (Windows, macOS, Linux)\n- Telemetry support with local file and Seq logging\n\n## Quick Start\n\n```bash\n# Install the tool\ndotnet tool install --global LofiBeats.Cli\n\n# Start playing some beats\nlofi play --style jazzy\n\n# Add some effects\nlofi effect --name reverb\nlofi effect --name tapeflutter\nlofi effect --name vinyl\n\n# Control volume\nlofi volume 0.8\n\n# Stop playback\nlofi stop\n\n# Stop with tapestop effect\nlofi stop --tapestop\n\n# Play with custom BPM\nlofi play --style chillhop --bpm 82\n\n# Play in a specific key\nlofi play --style jazzy --key F#\nlofi play --style chillhop --key Bb\n\n# Crossfade between patterns\nlofi play --style jazzy --transition crossfade # Default 2s crossfade\nlofi play --style chillhop --transition crossfade --xfade-duration 3 # Custom duration\nlofi play --style hiphop --transition crossfade --after 30s # Scheduled crossfade\n\n# Schedule playback to start later\nlofi play --style jazzy --after 5m     # Start playing in 5 minutes\nlofi stop --tapestop --after 30s       # Stop with effect in 30 seconds\n\n# Schedule playback to stop later\nlofi stop --after 10m\nlofi stop --tapestop --after 30s\n\n# Manage scheduled actions\nlofi schedule list                      # View all scheduled actions\nlofi schedule cancel \u003caction-id\u003e        # Cancel a specific action\n\n# Save current configuration as a preset\nlofi preset save mypreset.json\n\n# Load a saved preset\nlofi preset load mypreset.json\n\n# Save presets in a custom directory\nlofi preset save presets/chillvibes.json\n\n# Register your own samples\nlofi sample register kick /path/to/kick.wav\nlofi sample register snare /path/to/snare.wav\nlofi sample register hat /path/to/hihat.wav\n\n# Register samples with velocity layers (0-127)\nlofi sample register kick /path/to/soft_kick.wav --velocity 64\nlofi sample register kick /path/to/hard_kick.wav --velocity 127\n\n# List registered samples\nlofi sample list\n\n# Unregister samples\nlofi sample unregister kick        # Unregister a basic sample\nlofi sample unregister kick-soft   # Unregister a sample with all its velocity layers\n```\n\n## User Samples\n\nLofiBeats supports using your own audio samples for drum sounds. Samples are automatically managed and stored in your local application data directory.\n\nFor detailed information about sample management, velocity layers, supported formats, and best practices, see [User Samples Guide](docs/USER_SAMPLES.md).\n\n## Plugins\n\nLofiBeats supports custom audio effect plugins that extend the application's capabilities. The plugin system allows you to create and use your own audio effects.\n\nFor detailed information about creating plugins, installation, requirements, and best practices, see [Plugins Guide](docs/PLUGINS.md).\n\n## Architecture\n\nLofiBeats consists of three main components:\n\n1. **LofiBeats.Cli**: Command-line interface tool\n2. **LofiBeats.Service**: Background service with REST API and WebSockets support\n3. **LofiBeats.Core**: Core audio processing and effect implementation\n\n## Build Requirements\n\n- .NET 9.0 SDK\n- PowerShell 7+ (Windows) or Terminal (macOS/Linux)\n- Audio output device with working drivers\n\n### Platform-Specific Requirements\n\n#### Windows\n- NAudio native dependencies (included)\n- System.Management package for process management\n\n#### macOS\n- CoreAudio drivers\n- `ps` command available for process management\n\n#### Linux\n- ALSA audio system\n- `pkill` command available for process management\n\n## Building from Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/willibrandon/LofiBeats.git\ncd LofiBeats\n\n# Build the solution\ndotnet build\n\n# Run tests (platform-specific tests will be skipped on non-Windows platforms)\ndotnet test\n\n# Create platform-specific releases\n./scripts/publish.sh --runtime linux-x64 --version 1.0.0\n./scripts/publish.sh --runtime osx-x64 --version 1.0.0\n./scripts/publish.sh --runtime win-x64 --version 1.0.0\n```\n\n## Configuration\n\nThe application uses two configuration files:\n\n1. `cli.appsettings.json` - CLI configuration\n2. `service.appsettings.json` - Service configuration\n\nKey configuration options:\n\n```json\n{\n  \"Telemetry\": {\n    \"IsEnabled\": true,\n    \"EnableSeq\": false,\n    \"SeqServerUrl\": \"http://localhost:5341\",\n    \"EnableLocalFile\": true\n  }\n}\n```\n\n## API Endpoints\n\nThe service exposes the following REST API endpoints:\n\n- `POST /api/lofi/generate` - Generate a new beat pattern (supports `style`, `bpm`, and `key` parameters)\n- `POST /api/lofi/play` - Start playback (supports `style`, `bpm`, `key`, `transition`, and `xfadeDuration` parameters)\n- `POST /api/lofi/stop` - Stop playback\n- `POST /api/lofi/pause` - Pause playback\n- `POST /api/lofi/resume` - Resume playback\n- `POST /api/lofi/volume` - Set volume level\n- `POST /api/lofi/effect` - Add/remove effects\n- `POST /api/lofi/schedule-play` - Schedule a future playback\n- `POST /api/lofi/schedule-stop` - Schedule a future stop\n- `GET /api/lofi/preset/current` - Get current preset state\n- `POST /api/lofi/preset/apply` - Apply a preset configuration\n- `GET /healthz` - Health check endpoint\n\n## WebSockets Support\n\nThe service also provides real-time control and event notifications through WebSocket connections at `ws://localhost:5001/ws`.\n\n### Authentication\n\nWhen authentication is enabled, connect with a token:\n```\nws://localhost:5001/ws?token=your_auth_token\n```\n\n### Commands\n\nSend commands as JSON messages with the following format:\n```json\n{\n  \"type\": \"command\",\n  \"action\": \"play\",\n  \"payload\": {\n    \"style\": \"jazzy\",\n    \"bpm\": 85,\n    \"key\": \"C#\",\n    \"transition\": \"crossfade\",\n    \"xfadeDuration\": 2.0\n  }\n}\n```\n\nAvailable commands:\n- `play` - Start playback with options\n  ```json\n  {\n    \"style\": \"basic|jazzy|chillhop|hiphop\",\n    \"bpm\": 80,\n    \"key\": \"C|C#|D|Eb|E|F|F#|G|Ab|A|Bb|B\",\n    \"transition\": \"immediate|crossfade\",\n    \"xfadeDuration\": 2.0\n  }\n  ```\n- `stop` - Stop playback\n  ```json\n  {\n    \"tapestop\": false\n  }\n  ```\n- `volume` - Adjust volume\n  ```json\n  {\n    \"level\": 0.8\n  }\n  ```\n- `add-effect` - Add an audio effect\n  ```json\n  {\n    \"name\": \"reverb|vinyl|tapestop|tapeflutter\",\n    \"parameters\": {\n      \"key\": \"value\"\n    }\n  }\n  ```\n- `remove-effect` - Remove an audio effect\n  ```json\n  {\n    \"name\": \"reverb\"\n  }\n  ```\n- `sync-state` - Request current playback state\n\n### Events\n\nThe server broadcasts events in the following format:\n```json\n{\n  \"type\": \"event\",\n  \"action\": \"playback-started\",\n  \"payload\": {\n    \"style\": \"jazzy\",\n    \"bpm\": 85\n  }\n}\n```\n\nAvailable events:\n- `volume-changed` - Volume level changed\n- `playback-started` - Playback has started\n- `playback-stopped` - Playback has stopped\n- `beat-generated` - New beat pattern generated\n- `effect-added` - Audio effect was added\n- `effect-removed` - Audio effect was removed\n- `metrics-updated` - Performance metrics update\n\n### Error Messages\n\nError responses follow this format:\n```json\n{\n  \"type\": \"error\",\n  \"action\": \"unknown-command\",\n  \"payload\": {\n    \"message\": \"Unknown command: invalid-action\"\n  }\n}\n```\n\nError types:\n- `unknown-command` - Command not recognized\n- `invalid-payload` - Invalid command parameters\n- `auth-failed` - Authentication failure\n\n### Rate Limiting\n\n- Maximum message size: 4KB\n- Rate limit: 60 messages per minute per client\n- Maximum concurrent connections: 100\n\n## Development\n\n### Running Tests\n\n```bash\n# Run all tests\ndotnet test\n\n# Run specific test categories\ndotnet test --filter \"Category!=Platform_Specific\"\ndotnet test --filter \"Category=AI_Generated\"\n```\n\n### Test Container\n\nFor running tests in CI or containerized environments, we provide a Docker container with a pre-configured audio testing environment. See [CONTAINER.md](docs/CONTAINER.md) for details.\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Commit your changes\n4. Push to the branch\n5. Create a Pull Request\n\n## Telemetry\n\nThe application collects anonymous usage telemetry to improve the user experience. Data is stored in:\n\n- Windows: `%LOCALAPPDATA%\\LofiBeats\\Telemetry`\n- macOS: `~/Library/Application Support/LofiBeats/Telemetry`\n- Linux: `~/.local/share/LofiBeats/Telemetry`\n\nTelemetry can be disabled in the configuration file.\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwillibrandon%2Flofibeats","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwillibrandon%2Flofibeats","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwillibrandon%2Flofibeats/lists"}