Slopsmith

A self-contained web application for browsing, playing, and practicing interactive music notation for a full band — guitar, bass, keys, drums, and vocals — extended by a large plugin system. Runs entirely in Docker — no local dependencies required.

The screenshot above shows the 3D Highway — a bundled visualization plugin selectable from the viz picker, featuring depth-aware camera, lighting, and per-string lane glow.

The Classic 2D Highway is also available in the picker for low-powered devices.

Features

Library Browser

Grid View — album art cards with arrangement badges, tuning, lyrics indicator
Artist/Album Tree View — hierarchical browser with letter filter (A-Z), expandable artist and album groups
Search — filter by song title, artist, or album name
Sort — by artist, title, recently added, or tuning
Favorites — mark songs with a heart, browse favorites in a dedicated view
Edit Metadata — update song title, artist, album, and album art directly from the library
Retune to E Standard — pitch-shift songs in Eb/D/C#/C Standard to E Standard with one click

Note Highway Player

A real-time note highway that renders arrangements as scrolling, fret-positioned notes. Bundled visualization options include a 3D highway with depth-aware camera, lighting, and per-string lane glow, and a classic 2D highway selectable from the visualization picker.

Note rendering:

Fret-positioned notes with string colors (red, orange, blue, orange, green, purple)
Open string bars spanning the highway
Chord brackets connecting chord notes with chord name labels
Sustain tails that stay visible until the sustain finishes

Techniques:

Bends with curved arrows and labels (1/2, full, 1-1/2, 2)
Unison bends with dashed connector and "U" label
Slides (diagonal arrow)
Hammer-ons / Pull-offs / Taps (H/P/T labels)
Palm mutes (PM label)
Vibrato (animated sustain)
Tremolo (wavy line)
Accents (> marker)
Harmonics (diamond shape)
Pinch harmonics (diamond + PH label)

Additional features:

Synced lyrics display (phrase-based, multi-row, karaoke highlighting) — toggleable
Dynamic anchor zoom — fret range adjusts smoothly, looks ahead at upcoming notes
Arrangement switcher — switch between Lead, Rhythm, Bass during playback
Speed control — continuous slider from 0.25x to 1.50x
Volume control

Practice Tools

A-B Looping — set start (A) and end (B) points to repeat a section
Saved Loops — name and save multiple loop sections per song, persisted across sessions
4-Count Click — tempo-matched metronome count-in (1-2-3-4) before each loop repetition
Rewind Effect — highway smoothly rewinds to the loop start point

Song Creation

Create from Guitar Pro Tab — search Ultimate Guitar for GP3/GP4/GP5 tabs and convert them to playable songs with MIDI audio (available as a plugin)

Compatibility

Supports custom songs (CDLC) in PSARC and Sloppak formats
Reads arrangement names from manifest JSON (accurate Lead/Rhythm/Bass identification)

Scalability

In-memory PSARC scanning — reads metadata without writing to disk
Parallel scanning — 8-thread metadata extraction
Server-side pagination and search — SQLite-backed, handles 80,000+ songs
Non-blocking scan — browse already-scanned songs while import continues in background

Quick Start

Prerequisites

Docker and Docker Compose

Run

Clone the repository:

git clone https://github.com/carochacs/slopsmith.git
cd slopsmith

Set your DLC folder path and start:

DLC_PATH=/path/to/your/songs docker compose up -d

Open http://localhost:8000 in your browser.

On first launch, the app scans your DLC folder and imports metadata. A progress banner shows at the bottom of the screen. The library is usable while the scan runs.

Configuration

DLC Folder — set in Settings or via the DLC_PATH environment variable
Default Arrangement — choose Lead, Rhythm, or Bass as the default when opening songs (Settings)

Logging

Control log verbosity and format via environment variables:

Variable	Default	Description
`LOG_LEVEL`	`INFO`	Severity threshold: `DEBUG`, `INFO`, `WARNING`, or `ERROR`
`LOG_FORMAT`	`text`	`text` for coloured console output; `json` for structured output (Loki, ELK, Promtail)
`LOG_FILE`	(unset)	If set, also write logs to this path (e.g. `/config/slopsmith.log`)

Reporting Bugs / Diagnostics

When you hit a bug, Settings → Diagnostics → Export Diagnostics produces a single zip containing everything a maintainer (or AI agent) needs to triage:

Server logs (tail of LOG_FILE)
System info (Python, OS, Slopsmith version)
Hardware (CPU, RAM, GPU) — works in Docker, Electron (slopsmith-desktop), or bare Python
Plugin inventory with git commit SHAs (so we know exactly which build you're on) — including orphaned plugins that failed to load
Browser console transcript (all console.log/info/warn/error/debug + uncaught errors + promise rejections, last 500 entries)
Browser hardware (WebGL renderer, WebGPU adapter)
Per-plugin contributed diagnostics (when plugins opt in)

Privacy: redaction is on by default. DLC paths, song filenames, IP addresses, and bearer tokens are replaced with stable hashed tokens (<song:a3f1c2d4>) before the bundle is created. Click Preview Bundle to see exactly what's about to be exported.

Set LOG_FILE first if you want server logs included — without it the bundle still ships system + hardware + browser console, but the logs/ section will be empty.

The bundle layout and per-file schemas are fully documented in docs/diagnostics-bundle-spec.md. Top-level manifest.json carries a schema field on every JSON data file so AI agents can dispatch by version.

Attach the zip to a GitHub issue or share with whoever's helping you debug.

Docker Compose Example

services:
  web:
    build: .
    ports:
      - "8000:8000"
    volumes:
      # Mount your song folder
      - /path/to/your/songs:/dlc
      # Persistent config, cache, and favorites
      - slopsmith-config:/config
      # Optional: mount plugins for development
      # - ./plugins:/app/plugins
    environment:
      - DLC_DIR=/dlc
      - CONFIG_DIR=/config

volumes:
  slopsmith-config:

Apache Reverse Proxy

To expose Slopsmith behind an Apache reverse proxy, add the following configuration to your virtual host:

ProxyPass /slopsmith/ http://localhost:8000/
ProxyPassReverse /slopsmith/ http://localhost:8000/

ProxyPass /api/ http://localhost:8000/api/
ProxyPassReverse /api/ http://localhost:8000/api/

ProxyPass /static/ http://localhost:8000/static/
ProxyPassReverse /static/ http://localhost:8000/static/

ProxyPass /ws ws://localhost:8000/ws

ProxyPass /audio/ http://localhost:8000/audio/
ProxyPassReverse /audio/ http://localhost:8000/audio/

Ensure the required Apache modules are enabled:

sudo a2enmod proxy
sudo a2enmod proxy_http
sudo a2enmod proxy_wstunnel

Then restart Apache:

sudo systemctl restart apache2

Note: If Slopsmith is running on a different server, replace localhost:8000 with the appropriate URL or IP address (e.g., http://192.168.1.100:8000 or http://slopsmith.internal:8000).

Screensaver during playback: Slopsmith holds a Screen Wake Lock while a song plays so the display/screensaver doesn't kick in mid-song. The browser Wake Lock API is secure-context only, so this works on localhost, over HTTPS, and in the desktop app — but not over plain HTTP to a LAN IP (e.g. http://192.168.1.100:8000), where browsers don't expose the API. For screensaver suppression on a remote browser, front Slopsmith with HTTPS (e.g. via the reverse-proxy setup above plus TLS) or use the desktop app, which keeps the display awake natively.

Important: Even though the app entrypoint is proxied at /slopsmith, Slopsmith currently uses absolute frontend paths (for example /static/... and /api/...). That is why the config also proxies /api, /static, /ws, and /audio at the virtual-host root. These root routes will be exposed and can conflict with an existing site that already uses the same paths.

Slopsmith is not fully base-path aware yet, so it cannot be cleanly nested entirely under /slopsmith without additional rewriting or app changes. If you need to avoid route collisions, use a dedicated subdomain (for example slopsmith.your-domain) as the cleanest option.

Proxmox LXC Container

build-proxmox-ct.sh builds a self-contained Proxmox LXC rootfs tarball from WSL2. It bootstraps a Debian Trixie rootfs, installs the runtime dependencies (Python, FFmpeg, fluidsynth, vgmstream) plus a build-only .NET SDK, builds RsCli, copies the app, removes the .NET SDK, and packages the result as a .tar.zst importable by pct restore.

# Prerequisites (WSL2):
sudo apt install debootstrap systemd-container tar zstd curl unzip git

# Build (run from repo root):
sudo bash build-proxmox-ct.sh amd64 slopsmith-ct

# Transfer + import on Proxmox:
scp slopsmith-ct.tar.zst root@proxmox:/var/lib/vz/template/cache/
pct restore 200 /var/lib/vz/template/cache/slopsmith-ct.tar.zst \
    --storage local-lvm --rootfs 8 --memory 2048 --cores 2 \
    --net0 name=eth0,bridge=vmbr0,ip=dhcp --unprivileged 1 --start 1

Override the song source directory via environment, using sudo env so the variable survives sudo: sudo env SONG_SRC_DIR=/path/to/your/songs bash build-proxmox-ct.sh amd64 slopsmith-ct.

The build copies *_p.psarc files from ${SONG_SRC_DIR}/dlc/ — point the variable at the source root containing the dlc/ folder.

The build verifies downloaded files (vgmstream, dotnet-install.sh) against pinned SHA256 hashes. Set SKIP_HASH_CHECK=1 to bypass verification — useful when an upstream artifact (e.g. dot.net/v1/dotnet-install.sh) rolls and the pinned hash hasn't been refreshed yet:

sudo env SKIP_HASH_CHECK=1 bash build-proxmox-ct.sh amd64 slopsmith-ct

The script is linted with shellcheck. Only amd64 is supported out of the box; arm64 requires qemu-user-static + binfmt registration.

Portainer Setup

This guide walks through installing Docker, Portainer, and Slopsmith on Ubuntu.

Step 1: Update Package Lists & install docker

sudo apt update
sudo apt install docker.io -y
sudo usermod -aG docker $USER

Step 2: Install Portainer on Ubuntu

sudo docker pull portainer/portainer-ce:latest
sudo docker run -d -p 9000:9000 --restart always -v /var/run/docker.sock:/var/run/docker.sock portainer/portainer-ce:latest

Step 3: Access the Portainer Web Interface Open the following URL in your browser:

• http://server-ip:9000

Step 4: Pull the Slopsmith Image In Portainer, go to the Images tab and build a new image using the following settings:

• Image Name: slopsmith:latest

• Repository URL: https://github.com/carochacs/slopsmith.git

Step 5: Create a Stack for Slopsmith Click '+ Add Stack' and paste the following Docker Compose configuration into the editor. Replace '/path/to/dlc/' with the correct path where your dlc is on your host system.

version: "3.9"

services:
  web:
    image: slopsmith:latest
    container_name: slopsmith-web
    restart: unless-stopped

    ports:
      - "7000:8000"

    volumes:
      - /path/to/dlc/:/dlc
      - slopsmith-config:/config

    environment:
      DLC_DIR: /dlc
      CONFIG_DIR: /config

volumes
  slopsmith-config:

Click 'Deploy the stack'. This creates a container named 'slopsmith-web'. Access Slopsmith at: http://server-ip:7000

Step 6: Add the Update Manager

Clone the Update Manager repository on the host machine and copy to container.

cd /home/your_user
git clone https://github.com/carochacs/slopsmith-update-manager.git update_manager
sudo docker cp /home/your_user/update_manager slopsmith-web:/app/plugins/

Step 7: Restart the Slopsmith Container

In the Portainer web interface, go to Containers, select 'slopsmith-web', and restart the container.

Step 8: Install Recommended Plugins

Open Slopsmith at http://server-ip:7000 and install the following recommended plugins via the update manager:

• NAM Tone Engine - Enables Slopsmith to interface with your guitar/audio cable.
    1. Download amp models and cabinet IRs from: https://www.tone3000.com/
    
• Note Detection - Allows Slopsmith to detect the notes you are playing.

Plugins

Slopsmith supports a plugin system for extending functionality. Plugins can add navigation links, screens, settings sections, and API routes — all discovered automatically at startup.

Installing a Plugin

Drop the plugin folder into the plugins/ directory (or mount it as a Docker volume):

plugins/
  my_plugin/
    plugin.json
    routes.py
    screen.html
    screen.js
    settings.html  (optional)

Then restart the container. The plugin's nav link, screen, and settings will appear automatically.

Plugin Structure

Each plugin requires a plugin.json manifest:

{
  "id": "my_plugin",
  "name": "My Plugin",
  "version": "1.0.0",
  "nav": {
    "label": "My Feature",
    "screen": "my-screen"
  },
  "screen": "screen.html",
  "script": "screen.js",
  "settings": { "html": "settings.html" },
  "routes": "routes.py"
}

Field	Required	Description
id	Yes	Unique identifier, used in API paths
name	Yes	Display name
nav	No	Navigation link with label and screen ID
screen	No	HTML file for the plugin screen content
script	No	JavaScript file loaded after the screen is injected
settings	No	Object with html field pointing to a settings HTML fragment
routes	No	Python module with a setup(app, context) function for API routes

Plugin API Routes

The routes.py module must export a setup(app, context) function:

def setup(app, context):
    config_dir = context["config_dir"]    # Path to config directory
    get_dlc_dir = context["get_dlc_dir"]  # Function returning DLC Path
    meta_db = context["meta_db"]          # MetadataDB instance
    extract_meta = context["extract_meta"] # Function to extract PSARC metadata

    @app.get("/api/plugins/my_plugin/search")
    def search(q: str):
        # Your logic here
        return {"results": []}

Routes are registered under /api/plugins/{plugin_id}/ to avoid conflicts.

Plugin Frontend

screen.html — HTML fragment (no <html> or <body> tags). Injected into a <div class="screen"> container.
screen.js — JavaScript loaded after the HTML. Has access to all core functions (showScreen(), esc(), formatTime(), etc.).
settings.html — HTML fragment injected into the Settings page.

Capability Pipelines

Plugins can declare runtime capability domains in plugin.json so profiles, diagnostics, core services, and other plugins can reason about provider/requester relationships without private globals. Core registers manifest declarations before plugin scripts hydrate; runtime owners then attach command handlers through window.slopsmith.capabilities.

The public flow for cross-plugin automation is claim, dispatch, then release. For example, NAM claims stems while AMP is enabled, dispatches stems.mute for the guitar target, and releases the claim when AMP stops. Stems owns the mute/restore snapshots and records manual overrides so a user stem toggle wins over automation for the current session.

See docs/capability-domains.md for manifest fields, runtime registration, diagnostics, idempotent hydration rules, and validation commands.

Available Plugins

Plugin	Description	Install
Split Screen	2-4 highway panels side-by-side for multi-arrangement practice	`git clone ...slopsmith-plugin-splitscreen.git splitscreen`
Sloppak Converter	Convert PSARC to .sloppak with Demucs stem splitting — bulk-select cards or one-click "convert all PSARCs missing a sloppak", with a Conversions queue dashboard (pause/resume, retry, per-job metadata + Demucs result summary)	`git clone ...slopsmith-plugin-sloppak-converter.git sloppak_converter`
Stems Mixer	Per-stem mute/volume controls for .sloppak songs	`git clone ...slopsmith-plugin-stems.git stems`
Guitar Theory Lab	Explore scales, chords, intervals, tunings, and voicings on a fully interactive fretboard	`git clone ...slopsmith-plugin-guitar-theory.git guitar-theory-lab`
MIDI Capo	MIDI capo control for real-time transposition	`git clone ...slopsmith-plugin-midi-capo.git midi_capo`
Find More	Search for more songs by the same artist	`git clone ...slopsmith-plugin-find-more.git find_more`
Invert Highway	Flip the highway note direction	`git clone ...slopsmith-plugin-invert-highway.git invert_highway`
Themes	Offers several basic recolorings of the interface	`git clone ...slopsmith-plugin-themes.git themes`
Update Manager	Installs, updates, and uninstalls other plugins and the slopsmith core itself	`git clone ...slopsmith-update-manager.git update_manager`
Tuner	Floating tuner with customizable tunings	`git clone ...slopsmith-plugin-tuner.git tuner`
Simplify Chords	Changes complex chords on the note highway to simpler ones. Inspired by Ultimate Guitar's Simplify button.	`git clone ...slopsmith-plugin-simplify-chords.git simplify-chords`
Key Bindings	Highway key bindings for keyboard and TV remote	`git clone ...slopsmith-plugin-key-bindings.git key_bindings`
Folder Organizer	Organize your sloppak DLC songs into a folder tree view, grouped by subfolder name	`git clone ...slopsmith-plugin-folder-organizer.git folder-organizer`
SlopScale	Scale, arpeggio, and sweep-arpeggio practice routines with 3D highway, 2D highway, and tab renderers. Pathway selector, CAGED shape-run arpeggios, and generated audio backing.	`git clone ...slopsmith-plugin-slopscale.git slopscale`
NAM Rig Builder	Map chained NAM neural-amp rigs (tone3000 captures + IRs) — full pedal→amp→cab playback, per-stage bypass, and a gear catalog	`git clone ...slopsmith-plugin-nam-rig-builder.git nam_rig_builder`
Audio Preview	Quick audio previews from library cards with configurable start time, volume, and duration	`git clone ...slopsmith-plugin-audio-preview.git audio_preview`
Per-Song Mastery	Remembers the difficulty slider position for each song	`git clone ...slopsmith-plugin-song-mastery.git song_mastery`
Song Preview	Quickly hear previews of songs in your library with a clean visual indicator of what's playing. Supports .psarc, .sloppak and loose folders song formats.	`git clone ...slopsmith-plugin-song-preview.git song_preview`
Mobile Note Highway	Touch-optimized player with collapsible controls, highway gestures, and device-adaptive layouts for phones and tablets	`git clone ...slopsmith-plugin-mobile-note-highway.git mobile_note_highway`
Shuffle	Random playback from your library — artist & tuning filters, auto-advance with countdown popup	`git clone https://github.com/Erikcb91/Slopsmith-Shuffle-Mode.git shuffle`
Jumping Tab	Yousician-style 2D horizontal tab with trajectory arcs and hopping ball	`git clone ...slopsmith-plugin-jumpingtab.git jumpingtab`

Install any plugin by cloning it into your plugins/ directory and restarting:

cd plugins
git clone https://github.com/topkoa/slopsmith-plugin-splitscreen.git splitscreen
docker compose restart

Documentation

Sloppak format — developer guide — schema, wire format, and how to extend the format with new data types
Sloppak hand-editing — user guide — record your own stem, fix metadata, swap cover art
Diagnostics bundle spec — layout and per-file schemas of the Export Diagnostics bundle

AI Agent Guide

This repo includes a CLAUDE.md file with architecture overview, plugin conventions, and best practices for AI coding agents (Claude Code, etc.). If you're using AI tools to contribute, the guide is picked up automatically. If you're updating conventions or patterns, please keep CLAUDE.md in sync.

Tech Stack

Backend: Python / FastAPI / SQLite / WebSocket
Frontend: Vanilla JS / Canvas 2D / Tailwind CSS (CDN)
PSARC: Custom AES-CFB-128 decryptor with in-memory reading
Note Compiler: F# CLI tool wrapping a third-party MIT-licensed .NET library (see rscli/LICENSE)
Audio: vgmstream (WEM decode) / FFmpeg / FluidSynth (MIDI render) / rubberband (pitch shift)
Docker: Self-contained image with all dependencies

Running tests

Core library modules have a small pytest suite (pure functions only — no fixtures, no Docker). To run it locally:

pip install -r requirements.txt -r requirements-test.txt
pytest

CI runs the same suite on every push and PR against main (see .github/workflows/tests.yml). Contributions adding tests are welcome — the current targets are lib/tunings.py and lib/song.py; natural follow-ups would be the pure helpers in lib/sloppak_convert.py and the tempo/tick math in lib/gp2rs.py.

Browser tests

Keyboard shortcuts and UI interactions are tested with Playwright. To run them:

# Start the server first
DLC_PATH=/path/to/your/dlc docker compose up -d

# Install dependencies
npm install
npm run install:playwright

# Run tests
npm test

See tests/browser/README.md for full documentation on browser tests.

Support Slopsmith

Slopsmith is free, open-source software (AGPL-3.0), built and maintained in spare time. Running it — AI-assisted development, code-signing certificates, build CI, and test/audio compute — costs money.

If Slopsmith is useful to you, you can help cover those costs:

❤️ Patreon — recurring support; patrons get a spot on the supporter wall and a role in the community Discord.
☕ Ko-fi — one-time tip, any amount.
💬 Discord — join the community (free for everyone).

Even €1 genuinely helps — your support funds open-source software development.

License

Slopsmith is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0-only).

You are free to use, modify, and redistribute Slopsmith — including running it on your own server. If you distribute modified versions, or run a modified version that interacts with users over a network, you must make the corresponding source code available under the same license. See CONTRIBUTING.md for contributor terms (DCO sign-off, plugin licensing policy).

Bundled and vendored third-party code retains its original license — see rscli/LICENSE for the F# wrapper's dependencies, and individual plugin repositories for plugin licenses.

Name		Name	Last commit message	Last commit date
Latest commit History 53 Commits
.claude/skills		.claude/skills
.github		.github
.specify		.specify
docs		docs
lib		lib
plugins		plugins
rscli		rscli
scripts		scripts
specs		specs
static		static
tests		tests
.dockerignore		.dockerignore
.gitattributes		.gitattributes
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
SUPPORTERS.md		SUPPORTERS.md
TODO.md		TODO.md
VERSION		VERSION
build-proxmox-ct.sh		build-proxmox-ct.sh
docker-compose.nas.yml		docker-compose.nas.yml
docker-compose.yml		docker-compose.yml
main.py		main.py
package-lock.json		package-lock.json
package.json		package.json
playwright.config.ts		playwright.config.ts
pyproject.toml		pyproject.toml
requirements-test.txt		requirements-test.txt
requirements.txt		requirements.txt
server.py		server.py
tailwind.config.js		tailwind.config.js
uv.lock		uv.lock

Folders and files

Latest commit

History

Repository files navigation

Slopsmith

Features

Library Browser

Note Highway Player

Practice Tools

Song Creation

Compatibility

Scalability

Quick Start

Prerequisites

Run

Configuration

Logging

Reporting Bugs / Diagnostics

Docker Compose Example

Apache Reverse Proxy

Proxmox LXC Container

Portainer Setup

Plugins

Installing a Plugin

Plugin Structure

Plugin API Routes

Plugin Frontend

Capability Pipelines

Available Plugins

Documentation

AI Agent Guide

Tech Stack

Running tests

Browser tests

Support Slopsmith

License

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages