Plinken Remote

Plinken Remote is an iOS companion app that lets you control Plinken from your iPhone or iPad over your local network. It communicates using OSC (Open Sound Control) for parameter control and RTP for live camera streaming.

Architecture

The Plinken desktop app runs three network services that the iOS app connects to:

Service	Default Port	Protocol	Purpose
Config Server	9100	HTTP (TCP)	Auto-discovery and configuration
OSC Listener	9000	UDP	Receives control messages from iOS
OSC Reply	9001	UDP	Sends state updates back to iOS
RTP Video	5004	UDP	Receives camera video stream from iOS

Config Server

When the iOS app connects, it sends an HTTP GET request to the config server. Plinken responds with a JSON payload:

{
  "oscPort": 9000,
  "oscReplyPort": 9001,
  "rtpPort": 5004,
  "name": "Plinken",
  "version": "0.1.0"
}

The config server:

Runs on an Axum HTTP server bound to 0.0.0.0:9100
Tracks connected clients by IP address with connection time and last activity
Any route (/config or fallback) returns the same configuration JSON

Client Tracking

Plinken maintains a registry of connected Remote clients:

Property	Type	Description
`ip`	string	Client IP address
`name`	string	Device name (if provided)
`connected_at`	Instant	When the client first connected
`last_activity`	Instant	Last time any activity was received

Client activity is updated whenever:

The iOS app fetches the config endpoint
OSC messages arrive from the client’s IP

Getting Started

1. Same Network

Ensure your iPhone/iPad and your Mac are on the same Wi-Fi network. For lowest latency, use a 5 GHz network.

2. Launch Plinken

Open Plinken on your Mac. The config server starts automatically on port 9100. Verify it’s running in Settings → OSC or check the status indicator.

3. Connect from iOS

Open Plinken Remote on your iPhone or iPad:

The app automatically discovers Plinken via the config endpoint
If auto-discovery fails, tap Connection Settings and enter your Mac’s IP address manually
Once connected, the app fetches the config JSON and establishes OSC communication

4. Control Your Session

The iOS app provides:

Tab	Features
Transport	Play, stop, record, timeline position, cycle toggle
Control Surface	Touch faders and XY pad for real-time parameter control
Actions	Quick-access buttons for common Plinken commands
Camera	Stream device camera into Plinken

Features

Transport Control

Control playback directly from your device:

Play / Stop — Toggle playback
Record — Arm and trigger recording
Rewind / Forward — Navigate the timeline
Cycle — Toggle loop mode
Tap Tempo — Tap to set BPM

All transport commands are sent as OSC messages to port 9000 and translated to Plinken’s internal command system.

Control Surface

The touch control surface provides:

Faders — Vertical touch sliders mapped to track volumes, sends, or parameters
XY Pad — Two-axis touchpad for simultaneous control of two parameters
Buttons — Momentary and toggle buttons for mute, solo, arm

Controls send OSC values that Plinken maps to automation parameters.

Camera Input

Stream your iPhone or iPad camera directly into Plinken’s compositor:

Open the Camera tab in Plinken Remote
Select front or back camera
The video feed is sent via RTP to port 5004
In Plinken, the feed appears as a live video source in the compositor

The RTP port is configurable — Plinken advertises the current port in the config JSON, and you can change it programmatically:

-- The RTP port is set internally; check Settings → OSC for current values

Automation Mapping

Map any iOS control to a Plinken parameter:

Long-press a control (fader, XY pad axis, or button) on the iOS app
Select Map to Parameter
Move the target parameter in Plinken — auto-detection captures the mapping
The mapping is saved and synced via OSC

Network Configuration

Ports

Port	Service	Configurable
9100	HTTP Config Server	Start/stop via API
9000	OSC Listener (incoming)	Via Settings → OSC
9001	OSC Reply (outgoing)	Fixed default
5004	RTP Video (incoming)	Via `set_rtp_port()`

Firewall

If you’re using a firewall, ensure the following ports are open:

TCP 9100 — Config server (HTTP)
UDP 9000 — OSC control messages
UDP 9001 — OSC reply/feedback
UDP 5004 — RTP video stream

API

The remote server can be controlled programmatically:

Function	Description
`start(port)`	Start the config server on specified port
`stop()`	Stop the config server and clear client registry
`is_running()`	Check if the server is running
`port()`	Get the current listening port
`get_clients()`	Get list of connected clients
`touch_client(ip)`	Update last activity for a client IP
`set_rtp_port(port)`	Change the RTP port advertised to clients
`rtp_port()`	Get the current RTP port

Troubleshooting

Problem	Solution
Can’t find Plinken	Verify both devices are on the same network. Check that port 9100 is not blocked by a firewall.
High latency	Use 5 GHz Wi-Fi. Avoid Bluetooth interference. Close bandwidth-heavy apps.
Camera not showing	Grant camera permission to Plinken Remote in iOS Settings. Check that RTP port 5004 is open.
Controls unresponsive	Check the OSC listener status in Settings → OSC. Verify UDP 9000 is open.
Connection drops	The config server tracks client activity. If no activity is received, the client entry becomes stale. Reconnect from the iOS app.