control-surface

Generate TouchOSC .tosc files from JSON surface definitions.

2|Updated Jun 20, 2026
One-click install
npx skills add https://github.com/Impractical-Instruments/reuben --skill control-surface
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: control-surface
Source: https://github.com/Impractical-Instruments/reuben/tree/main/.claude/skills/control-surface
Command: npx skills add https://github.com/Impractical-Instruments/reuben --skill control-surface

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve?

This skill solves the friction of creating and maintaining custom control interfaces for musical instruments, ensuring that the presentation layer (UI) stays perfectly synced with the instrument's underlying engine contract.

Core Features & Use Cases

  • Durable UI Authoring: Edit JSON surface documents to define widgets, labels, and groupings that persist across instrument changes.
  • Deterministic Projection: Automatically generate TouchOSC (.tosc) files that are guaranteed to match the instrument's interface pipes.
  • Use Case: When you add a new filter parameter to your instrument, use this skill to instantly update your tablet's control layout without manually re-mapping OSC addresses or re-drawing widgets.

Quick Start

Use the control-surface skill to generate a new TouchOSC layout for the instrument file located at instruments/my-synth.json.

Frequently Asked Questions about control-surface

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I generate a TouchOSC layout from an instrument definition?

TouchOSC layout generation requires Python 3 to execute deterministic projection logic that transforms JSON surface definitions into valid .tosc binary files. You resolve a presentation document against engine interface pipes to map widget inputs to OSC addresses while enforcing range constraints and layout groupings.

What is the best way to keep my TouchOSC UI synced with my instrument's parameters?

Keep your TouchOSC UI synced with your instrument by authoring durable JSON surface documents that define widgets, labels, and groupings. The deterministic projection automatically ensures the presentation layer matches the engine contract, preventing manual re-mapping of OSC addresses when instrument parameters change.

Do I need Python 3 to create .tosc files for my musical instruments?

Yes, Python 3 is required to execute the deterministic projection logic that transforms JSON surface definitions into valid .tosc binary files. This guarantees the generated TouchOSC layouts match your musical instrument's interface pipes and range constraints.

Can I edit widget groups and labels in TouchOSC without redrawing the layout?

You can edit JSON surface documents to define and modify widgets, labels, and layout groupings that persist across instrument changes. This allows you to update your tablet's control layout without manually re-drawing widgets or re-mapping OSC addresses.

How does mapping widget inputs to OSC addresses work with range constraints?

Mapping widget inputs to OSC addresses works by resolving JSON presentation documents against engine interface pipes. The deterministic projection logic enforces range constraints and layout groupings to ensure the UI definitions accurately control musical instrument parameters via OSC messages.

What are the limitations of generating .tosc binary files deterministically?

The deterministic .tosc binary file generation is limited to resolving presentation documents against defined engine interface pipes. It requires a JSON surface definition and Python 3 environment to execute the projection logic, focusing strictly on mapping widget inputs to OSC addresses with enforced range constraints.