open404

An open-source, cross-platform Go library, toolkit, and CLI for the Roland SP-404MKII creative sampler and effector.

🌐 Website & Live Pad Sampler: https://iare-digital.github.io/open404/

Built entirely upon the reverse-engineered USB CDC-ACM serial protocol and standard MIDI specifications, open404 unlocks programmatic remote control, automation, sample management, and custom integrations for beatmakers, performers, and developers.

[!WARNING]

Firmware Compatibility & Disclaimer

• Verified Firmware: Tested and verified on Roland SP-404MKII firmware v5.51. Future or previous firmware releases may modify internal memory offsets, SysEx file structures, or opcode behaviors.
• No Affiliation: open404 is an independent, community-driven open-source project and is not affiliated, associated, authorized, endorsed by, or in any way officially connected with Roland Corporation. "Roland" and "SP-404MKII" are registered trademarks of Roland Corporation.
• No Liability: This software communicates directly with hardware flash storage and internal device memory via reverse-engineered protocols. It is provided "as is", without warranty of any kind, express or implied. In no event shall the authors or contributors be liable for any claim, damages, data loss, project corruption, hardware malfunction, or bricked devices arising from the use of this software. Always back up your projects and SD cards before performing sample imports, exports, or parameter operations.

Highlights

• Cross-Platform & Zero CGO: Pure Go implementation that cross-compiles cleanly to Linux (x86_64, arm64), macOS (Intel, Apple Silicon), and Windows.
• 100% Reverse-Engineered Protocol: Fully decoded binary protocol covering hardware buttons, pad auditioning, parameter tweaking, pattern sequencing, and file streaming.
• Connection Manager & Keepalive: Automatic serial port discovery (0582:02E7) with a resilient background heartbeat loop (fe 66 every 500ms) and clean teardown.
• Bidirectional Sample I/O: Import and export standard .wav files natively. The protocol handles automatic PC-side SP-404 MKII RFWV header generation (including the reverse-engineered MD5 / MSVCRT-rand checksums) to perfectly match the hardware's expected memory layout.
• Full Project Backup & Restore: Complete one-command backup and restore of all 160 sample pads (Banks A–J) and pattern sequences (PTN00001–PTN00160) into structured directories or portable .tar.gz archives with a portable project.json manifest.
• Pattern Sequence Extraction: Native conversion of Roland's proprietary .BIN pattern memory files into standard .mid (SMF0) MIDI files.
• Granular Parameter Control: Full support for 30+ pad parameters (Volume, Pan, BPM, Gate, Loop, One-Shot, Envelope AHR, VariPhrase, Pitch coarse/fine, Vinyl Sim, Mute Groups, Pad Links, Grooves).
• High-Level Client API: Idiomatic Go methods for controlling projects, pads, patterns, and global bank settings.
• Audio Interleaver & WAV Codec: Built-in WAV encoder/decoder and Left/Right channel interleaver for the SP-404's split stereo memory architecture.
• MIDI Control Subsystem: Pad note mappings (Banks A–J) and Control Change (CC) constants for EFX knobs 1–4, bus toggles, and pattern triggers.
• Tested Against Real Captures: Unit test suite verifying exact byte serialization against real Wireshark USB PCAP traces.

Architecture & Layout

open404/
├── cmd/
│   ├── sp404/            # CLI application ('open404')
│   └── open404d/         # HTTP REST API & Web Dashboard daemon
├── pkg/
│   ├── protocol/         # Pure protocol codecs, opcodes, RFWV headers, tests
│   ├── device/           # Serial I/O, auto-discovery, keepalive, client API, WAV
│   └── midi/             # MIDI CC constants, pad notes, message encoders
├── specs/                # Machine-readable Kaitai Struct (.ksy) protocol schemas
├── examples/             # Runnable example programs
├── docs/
│   └── PROTOCOL.md       # Complete reverse-engineered protocol reference
├── deploy/               # udev rules for Linux serial permissions
├── .github/workflows/    # CI & Release pipelines
└── go.mod

Installation & Deployment

Homebrew (macOS & Linux)

# Install directly from the formula URL
brew install https://raw.githubusercontent.com/iare-digital/open404/main/Formula/open404.rb

# Or install from a local clone
brew install --build-from-source Formula/open404.rb

# (Optional) Start open404d as a background service
brew services start open404

Nix & NixOS (Flakes)

# Run CLI directly without installing
nix run github:iare-digital/open404 -- ping

# Run Web Controller Daemon with Nix Flakes
nix run github:iare-digital/open404#open404d

# Install into current user profile
nix profile install github:iare-digital/open404

# Classic nix-build
nix-build default.nix

Debian / Ubuntu (.deb)

Download pre-built .deb packages with systemd service and udev rules from GitHub Releases:

# Download and install pre-built x86_64 package
curl -LO https://github.com/iare-digital/open404/releases/download/v0.1.0/open404_0.1.0_amd64.deb
sudo dpkg -i open404_0.1.0_amd64.deb

# For ARM64 (Raspberry Pi, etc.)
curl -LO https://github.com/iare-digital/open404/releases/download/v0.1.0/open404_0.1.0_arm64.deb
sudo dpkg -i open404_0.1.0_arm64.deb

# (Optional) Enable the open404d web service on system boot
sudo systemctl enable --now open404d

Docker & Docker Compose

Run the open404d web controller in a container with USB passthrough:

# Pull and run official multi-arch container image from GHCR
docker run -d --name open404d --device=/dev/ttyACM0:/dev/ttyACM0 -p 8404:8404 ghcr.io/iare-digital/open404/open404d:latest

# Or launch with Docker Compose
docker compose up -d

# Or build locally
docker build -t open404d .
docker run -d --name open404d --device=/dev/ttyACM0:/dev/ttyACM0 -p 8404:8404 open404d

Access the responsive web dashboard at http://localhost:8404.

Go Install

If you have Go installed, install binaries directly into your $GOPATH/bin:

go install github.com/iare-digital/open404/cmd/sp404@latest
go install github.com/iare-digital/open404/cmd/open404d@latest

Quickstart: CLI Tool

Building from Source (Go)

git clone https://github.com/iare-digital/open404.git
cd open404
make build-all

Linux Setup & Serial Permissions

On Linux, /dev/ttyACM* serial devices require read/write access. To enable non-root access:

Option A: Install the bundled udev rule (Recommended):

sudo cp deploy/99-sp404mk2.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules && sudo udevadm trigger

Option B: Add your user to the dialout group:

sudo usermod -aG dialout $USER
newgrp dialout

(On macOS and Windows, USB CDC-ACM devices are accessible out of the box without permission configuration).

Common Commands

# List all serial ports and detect connected SP-404MKII
./open404 ports

# Trigger the hardware [EXIT] button (dismisses menus / returns to home screen)
./open404 exit

# Switch active project (1 through 16)
./open404 project select 2

# Rename a project
./open404 project rename 2 "CHILL_BEATS"

# Backup an entire project (all 160 pads across Banks A-J + patterns)
# Dual-format: creates a directory or portable compressed .tar.gz archive
./open404 project backup 1 ./project1_backup.tar.gz
./open404 project backup 1 ./backup_folder/ --bank A        # Backup Bank A only
./open404 project backup 1 ./backup_folder/ --samples-only  # Backup samples without patterns

# Restore an entire project from a directory or .tar.gz archive
./open404 project restore ./project1_backup.tar.gz 2        # Restore archive into Project 2
./open404 project restore ./backup_folder/ 2 --force         # Overwrite existing pads without prompting

# Select and audition Pad 1 on Bank A
./open404 pad select A01
./open404 pad play A01
./open404 pad stop A01

# Adjust pad parameters
./open404 pad set-volume A01 100
./open404 pad set-pan A01 64
./open404 pad set-bpm A01 92.5

# Rename a sample on a pad
./open404 pad rename A01 "snare_01"

# Copy or delete a pad
./open404 pad copy A01 B01
./open404 pad delete B01

# Set project-wide master tempo
./open404 tempo 90.0

# Pattern sequencer operations
./open404 pattern copy A1 A2
./open404 pattern delete A2

# Export / import pattern sequences as Standard MIDI Files
./open404 --project 2 pattern export A1 my_pattern.mid
./open404 --project 2 pattern import A1 my_pattern.mid

# Export / import samples as standard WAV files
./open404 --project 1 sample export A1 kick.wav
./open404 --project 1 sample import kick.wav A1

# Audio editing & destructives
./open404 pad truncate A01         # Trim audio outside start/end markers
./open404 pad normalize A01        # Maximize sample peak amplitude
./open404 pad emphasis A01         # Apply high-frequency boost

# Bank-specific tempo & volume
./open404 bank A tempo 92.5        # Set Bank A tempo to 92.5 BPM
./open404 bank B volume 110        # Set Bank B volume to 110 (0-127)

# Realtime pad parameter control
./open404 param A1 pitch -12       # Pitch down 12 semitones (-24 to +24)
./open404 param A1 speed 85.0      # Time stretch to 85% (50.0 to 200.0)
./open404 param A1 gate on         # Enable gate mode (on/off)
./open404 param A1 loop on         # Enable loop (on/off)
./open404 param A1 reverse on      # Reverse playback (on/off)
./open404 param A1 oneshot on      # One-shot mode (on/off)
./open404 param A1 level 100       # Set volume (0-127)
./open404 param A1 pan 64          # Center pan (0-127)
./open404 param A1 roll 2          # Roll rate (0=Off, 1=1/2, 2=1/4, 3=1/8...)
./open404 param A1 bus bus1        # FX bus routing (dry, bus1, bus2)
./open404 param A1 mute-group 2    # Assign to Mute Group 2 (0=Off, 1-10=A-J)
./open404 param A1 link 3          # Pad link group (0=Off, 1-10=A-J)
./open404 param A1 envelope 10 50 20 # Attack=10, Hold=50, Release=20 (each 0-100)

Shell Autocompletion

open404 includes built-in tab autocompletion for commands, flags, and pad addresses (A01–J16):

# Bash (add to ~/.bashrc)
source <(open404 completion bash)

# Zsh (add to ~/.zshrc)
source <(open404 completion zsh)

# Fish (add to ~/.config/fish/config.fish)
open404 completion fish | source

# PowerShell (add to your $PROFILE)
open404 completion powershell | Out-String | Invoke-Expression

Environment Variables

Go Library Quickstart

Use open404 as a library in your own Go projects:

package main

import (
	"fmt"
	"log"
	"time"

	"github.com/iare-digital/open404/pkg/device"
	"github.com/iare-digital/open404/pkg/protocol"
)

func main() {
	// Automatically find and connect to the SP-404MKII over USB CDC-ACM
	client, err := device.ConnectAuto()
	if err != nil {
		log.Fatalf("Failed to connect: %v", err)
	}
	defer client.Close()

	fmt.Printf("Connected to SP-404MKII on %s\n", client.PortName())

	// Select Project 1
	_ = client.SelectProject(1)

	// Target Bank A Pad 1
	pad, _ := protocol.NewPad('A', 1)

	// Highlight the pad on the hardware screen
	_ = client.SelectPad(pad)

	// Tweak pad parameters
	_ = client.SetPadLevel(pad, 110)
	_ = client.SetPadPan(pad, 64) // Center
	_ = client.SetPadBPM(pad, 95.0)
	_ = client.SetPadEnvelope(pad, 0, 80, 50) // Attack=0, Hold=80, Release=50

	// Audition the sample
	_ = client.PreviewPlay(pad)
	time.Sleep(2 * time.Second)
	_ = client.PreviewStop(pad)

	// Dismiss any active menus
	_ = client.Exit()
}

MIDI Control

open404 provides complete MIDI constants and encoders for real-time performance:

import "github.com/iare-digital/open404/pkg/midi"

// Convert Bank B Pad 4 to standard MIDI Channel and Note
pad, _ := protocol.NewPad('B', 4)
channel, note := midi.PadToMIDINote(pad)
// channel = 1 (MIDI Ch 2), note = 39 (D#2)

// Build a Note On message (velocity 127)
noteOn, _ := midi.NewNoteOn(channel, note, 127)

// Control EFX Knobs (CC 16 = CTRL 1, CC 17 = CTRL 2, CC 18 = CTRL 3)
ctrl1, _ := midi.NewControlChange(0, midi.CCKnob1, 96)

// Toggle Bus 1 EFX On
bus1Toggle, _ := midi.NewControlChange(0, midi.CCBus1EffectOn, 127)

HTTP REST API & Web Dashboard (open404d)

open404d provides an embedded HTTP REST API and responsive HTML5 web controller dashboard:

# Start the daemon on http://localhost:8404
./open404d

# Or run on a custom network port
./open404d --addr :9000

Open http://localhost:8404 in your browser to interact with the responsive pad grid, audition sounds, dismiss menus with [EXIT], and adjust tempo from any desktop or mobile device on your local network.

REST Endpoints

• GET /api/status — Connection state and port info
• POST /api/exit — Trigger physical [EXIT] button
• POST /api/tempo — Set master BPM ({"bpm": 92.5})
• POST /api/pads/action — Pad operations (play, stop, select, delete, params, rename)

Runnable Examples

Check out the examples/ directory for self-contained, copy-pasteable programs:

• 01_basic_control: Connection setup, pad selection, auditioning audio, and dismissing menus.
• 02_sound_design: Envelope shaping (Attack, Hold, Release), pitch shifting, time-stretch rate, VariPhrase algorithm, voice modes, and mute groups.
• 03_midi_automation: Pad-to-MIDI note conversion and automated CC knob filter sweeps.

Run any example directly:

go run ./examples/01_basic_control/main.go

Protocol Reference

• Human-Readable Specification: For complete packet byte structures, opcodes, memory layout, SysEx wrappers, and Wireshark capture methodology, refer to the Complete Protocol Specification.
• Machine-Readable Schemas: For declarative YAML schemas that compile to parsers in Go, Python, Rust, C++, and TypeScript, or for visual debugging in Kaitai Web IDE, see the Kaitai Struct Specifications.

Running Tests

Unit & E2E Audio Pipeline Tests

All unit and audio pipeline tests run in < 0.2s without hardware:

make test
# Or: go test -v ./...

Test Coverage Report

Generate statement coverage across packages:

make cover

Development & Build

Makefile Targets

Git Pre-Commit Hooks

Two options are provided to ensure code formatting (gofmt), static analysis (go vet), compilation, and unit tests pass before every commit:

Option 1: Built-in Shell Hook (Zero dependencies):

make hooks

Option 2: Using the pre-commit framework:

pip install pre-commit
pre-commit install
pre-commit run --all-files

Cross-Compilation

open404 compiles cleanly across multiple architectures with zero CGO dependencies for Linux and Windows:

# Build for all supported platforms into dist/
make cross

# Or create release archives
make dist

[!NOTE] macOS builds use native IOKit CGO bindings via go.bug.st/serial and are built natively in GitHub Actions CI on macos-latest runners.

Roadmap

• USB CDC-ACM reverse engineering & packet mapping
• Protocol codecs & PCAP-verified unit tests
• Connection manager with background keepalive heartbeat
• High-level Client API for projects, pads, parameters, and patterns
• Pure Go WAV audio encoder/decoder & stereo interleaver
• E2E audio pipeline test with synthetic 48kHz audio fixtures
• CLI controller binary (open404)
• HTTP REST & Web Dashboard Daemon (open404d)
• Runnable developer example suite (examples/)
• Pattern SMF (.mid) sequence file exporter & importer
• Realtime pad parameter control (speed, pitch, gate, loop, reverse, roll)
• Full project backup & restore engine (.tar.gz archives & manifests)
• Model Context Protocol (MCP) server for AI assistants (Claude, Cursor, Antigravity)
• WebUSB / WebSerial browser controller
• Standalone desktop GUI librarian (Wails / Fyne)

Community & Contributing

Contributions are welcome! Please read our Contributing Guidelines and Code of Conduct before submitting pull requests.

• Bug Reports & Features: Please use our Issue Templates.
• Security & Hardware Safety: See SECURITY.md for responsible disclosure procedures.
• Changelog: See CHANGELOG.md for release notes.

Authors & Maintainers

• Joe Amorosa (404@iare.digital) - Creator, Protocol Reverse Engineering & Lead Maintainer (iare.digital)
• See AUTHORS.md for all project contributors.

License

MIT License. See LICENSE for details.