A CLI tool for generating and playing lofi beats with real-time effects.
$ dotnet add package LofiBeats.CliA cross-platform command-line tool and service for generating and playing lofi beats with real-time effects.
# Install the tool
dotnet tool install --global LofiBeats.Cli
# Start playing some beats
lofi play --style jazzy
# Add some effects
lofi effect --name reverb
lofi effect --name tapeflutter
lofi effect --name vinyl
# Control volume
lofi volume 0.8
# Stop playback
lofi stop
# Stop with tapestop effect
lofi stop --tapestop
# Play with custom BPM
lofi play --style chillhop --bpm 82
# Crossfade between patterns
lofi play --style jazzy --transition crossfade # Default 2s crossfade
lofi play --style chillhop --transition crossfade --xfade-duration 3 # Custom duration
lofi play --style hiphop --transition crossfade --after 30s # Scheduled crossfade
# Schedule playback to start later
lofi play --style jazzy --after 5m # Start playing in 5 minutes
lofi stop --tapestop --after 30s # Stop with effect in 30 seconds
# Schedule playback to stop later
lofi stop --after 10m
lofi stop --tapestop --after 30s
# Manage scheduled actions
lofi schedule list # View all scheduled actions
lofi schedule cancel <action-id> # Cancel a specific action
# Save current configuration as a preset
lofi preset save mypreset.json
# Load a saved preset
lofi preset load mypreset.json
# Save presets in a custom directory
lofi preset save presets/chillvibes.json
# Register your own samples
lofi sample register kick /path/to/kick.wav
lofi sample register snare /path/to/snare.wav
lofi sample register hat /path/to/hihat.wav
# Register samples with velocity layers (0-127)
lofi sample register kick /path/to/soft_kick.wav --velocity 64
lofi sample register kick /path/to/hard_kick.wav --velocity 127
# List registered samples
lofi sample list
# Unregister samples
lofi sample unregister kick # Unregister a basic sample
lofi sample unregister kick-soft # Unregister a sample with all its velocity layers
LofiBeats supports using your own audio samples for drum sounds. Samples are automatically managed and stored in your local application data directory.
For detailed information about sample management, velocity layers, supported formats, and best practices, see User Samples Guide.
LofiBeats consists of three main components:
ps command available for process managementpkill command available for process management# Clone the repository
git clone https://github.com/willibrandon/LofiBeats.git
cd LofiBeats
# Build the solution
dotnet build
# Run tests (platform-specific tests will be skipped on non-Windows platforms)
dotnet test
# Create platform-specific releases
./scripts/publish.sh --runtime linux-x64 --version 1.0.0
./scripts/publish.sh --runtime osx-x64 --version 1.0.0
./scripts/publish.sh --runtime win-x64 --version 1.0.0
The application uses two configuration files:
cli.appsettings.json - CLI configurationservice.appsettings.json - Service configurationKey configuration options:
{
"Telemetry": {
"IsEnabled": true,
"EnableSeq": false,
"SeqServerUrl": "http://localhost:5341",
"EnableLocalFile": true
}
}
The service exposes the following REST API endpoints:
POST /api/lofi/generate - Generate a new beat patternPOST /api/lofi/play - Start playback (supports crossfade with transition and xfadeDuration parameters)POST /api/lofi/stop - Stop playbackPOST /api/lofi/pause - Pause playbackPOST /api/lofi/resume - Resume playbackPOST /api/lofi/volume - Set volume levelPOST /api/lofi/effect - Add/remove effectsPOST /api/lofi/schedule-play - Schedule a future playbackPOST /api/lofi/schedule-stop - Schedule a future stopGET /api/lofi/preset/current - Get current preset statePOST /api/lofi/preset/apply - Apply a preset configurationGET /healthz - Health check endpointThe service also provides real-time control and event notifications through WebSocket connections at ws://localhost:5001/ws.
When authentication is enabled, connect with a token:
ws://localhost:5001/ws?token=your_auth_token
Send commands as JSON messages with the following format:
{
"type": "command",
"action": "play",
"payload": {
"style": "jazzy",
"bpm": 85,
"transition": "crossfade",
"xfadeDuration": 2.0
}
}
Available commands:
play - Start playback with options
{
"style": "basic|jazzy|chillhop|hiphop",
"bpm": 80,
"transition": "immediate|crossfade",
"xfadeDuration": 2.0
}
stop - Stop playback
{
"tapestop": false
}
volume - Adjust volume
{
"level": 0.8
}
add-effect - Add an audio effect
{
"name": "reverb|vinyl|tapestop|tapeflutter",
"parameters": {
"key": "value"
}
}
remove-effect - Remove an audio effect
{
"name": "reverb"
}
sync-state - Request current playback stateThe server broadcasts events in the following format:
{
"type": "event",
"action": "playback-started",
"payload": {
"style": "jazzy",
"bpm": 85
}
}
Available events:
volume-changed - Volume level changedplayback-started - Playback has startedplayback-stopped - Playback has stoppedbeat-generated - New beat pattern generatedeffect-added - Audio effect was addedeffect-removed - Audio effect was removedmetrics-updated - Performance metrics updateError responses follow this format:
{
"type": "error",
"action": "unknown-command",
"payload": {
"message": "Unknown command: invalid-action"
}
}
Error types:
unknown-command - Command not recognizedinvalid-payload - Invalid command parametersauth-failed - Authentication failure# Run all tests
dotnet test
# Run specific test categories
dotnet test --filter "Category!=Platform_Specific"
dotnet test --filter "Category=AI_Generated"
src/LofiBeats.Core/EffectsIAudioEffect interfaceEffectFactory.csFor running tests in CI or containerized environments, we provide a Docker container with a pre-configured audio testing environment. See CONTAINER.md for details.
The application collects anonymous usage telemetry to improve the user experience. Data is stored in:
%LOCALAPPDATA%\LofiBeats\Telemetry~/Library/Application Support/LofiBeats/Telemetry~/.local/share/LofiBeats/TelemetryTelemetry can be disabled in the configuration file.
This project is licensed under the MIT License - see the LICENSE file for details.