midi-harbor/specs/004-hardware-devices/spec.md

Feature Specification: Hardware Devices

Status: Implemented

Created: 2026-09-20

Scope: MIDI hardware attached to the computer, and ports other applications provide: finding it, following it as it is plugged in and out, recognising it again after a replug, telling identical devices apart, and a device another application holds. Carrying hardware over the network is user story 4, in 007-routing.

Split out of the original Midi Harbor specification on 2026-09-27. Requirement, success criterion, research and task numbers are the ones the original gave them, and the code cites them by number; the index says which spec holds each. The architecture, the daemon contract and the command-line contract are in 001-service-and-clients.

User Scenarios & Testing (mandatory)

Edge Cases

• Device claimed by another application: When a physical MIDI device is held exclusively by another application, Midi Harbor reports it as in use by another application rather than failing silently, and claims it when it becomes free.
• Identical devices: When two devices reporting the same name are attached at once, they are distinguished in the interface so routes address the right one.
• Device removed mid-message: When a device is unplugged partway through a system-exclusive transfer, the partial message is discarded rather than forwarded as corrupt data.

Requirements (mandatory)

Functional Requirements

Physical MIDI devices

• FR-015a: System MUST automatically discover and list physical MIDI hardware attached to the computer — USB MIDI interfaces, DIN interfaces, controllers, and keyboards — presenting each with its hardware-reported name.
• FR-015b: System MUST expose each physical MIDI input and output as an endpoint usable as a route source or destination, on equal terms with virtual ports, network sessions, and Bluetooth devices.
• FR-015c: System MUST detect physical devices being attached and removed while running, and update the endpoint list without the user refreshing anything or restarting the service.
• FR-015d: System MUST retain the configuration of routes referencing a physical device while that device is unplugged, and resume them automatically when the same device is reattached.
• FR-015e: System MUST identify a physical device stably enough that reattaching the same device — including to a different port on the same computer — restores its routes rather than presenting it as a new device.
• FR-015f: System MUST silence sounding notes at the destinations of a route when that route's physical source device is removed.
• FR-015g: System MUST distinguish two physically identical devices attached at the same time, so the user can tell them apart and route them separately.

Key Entities

• Physical MIDI Device: An endpoint representing MIDI hardware attached to this computer. Has a hardware-reported name, a stable identity that survives being unplugged and reattached, a present/absent status, and separate input and output sides.

Success Criteria (mandatory)

Measurable Outcomes

• SC-010a: A physical MIDI device plugged in while the service is running appears as a routable endpoint within 2 seconds, with no user action.
• SC-010c: Across 100 unplug-and-replug cycles of a routed physical device, 100% of routes resume automatically and zero notes are left sounding.

Assumptions

• Physical MIDI devices are accessed through the operating system's own MIDI layer, so any device the operating system already recognises is usable; vendor-specific drivers are out of scope.