Status and errors
Treefall APIs report whether an operation succeeded, was rejected before mutation, or failed while interacting with a provider. Preserve the status and its accompanying detail instead of converting every non-success into a generic “device” or “file” error.
The result classes
Section titled “The result classes”Use these result classes when choosing the next action:
- Operation completed: State or output is valid and may be consumed (
OK). - Input is malformed or outside the contract: Correct the caller’s values; no operation should be assumed (
InvalidParameter,InvalidHandle, orInvalidClipTrimPoints). - Capability or lifecycle is unavailable: Enable the provider, prepare the object, or use a supported surface (
NotSupported,NotReady, orNotInitialized). - Bounded capacity refused work: Retry from a control/message context after observing capacity, or report a deliberate refusal (
NotReady). - Provider or storage failed: Preserve the detail, stop relying on the failed result, and follow the relevant recovery procedure (
InternalError).
Result<T> carries both a typed SessionGraphError and an errorMessage. Check isOk() before consuming its value. C ABI callers receive an orpheus_status and can use orpheus_status_to_string() for a stable display label.
Audio-file operations
Section titled “Audio-file operations”getAudioFileCapabilities() is a policy and provider-availability query; it performs no media setup. Before creating a writer, call preflightAudioFileWrite(): invalid rate or channel counts produce InvalidParameter, an unsupported container produces NotSupported, invalid encoding produces InvalidParameter, and an absent provider produces NotReady. A successful preflight does not guarantee that opening the destination will succeed; destination creation can still return InternalError.
probeAudioFile() belongs on a control or background thread. An empty path is InvalidParameter, an absent provider is NotReady, and a missing, unreadable, or corrupt input is InternalError with the provider explanation. Invalid header fields are InvalidParameter. A probe is not a realtime operation and does not decode or calculate a media fingerprint.
Drivers and routes
Section titled “Drivers and routes”Use capability and route APIs to distinguish InputUnavailable, OutputUnavailable, SampleRateUnsupported, PermissionDenied, and BackendFailure. A terminal route outcome means rendering has stopped and requires an explicit initialize() with host-selected configuration. Do not silently select another endpoint. A requested output channel count is a contract: if the selected backend cannot provide it, handle the refusal rather than changing the count without user policy.
Transport capacity and preparation
Section titled “Transport capacity and preparation”Transport control calls can return NotReady when bounded command admission or source preparation cannot proceed. A registered source is prepared before its command is published. Preparation failure does not create a source-less playback command. A seek failure is atomic: it produces no command, cursor change, callback, or synthetic underrun event. processAudio() accepts only the configured planar buffer shape and frame bound; malformed shapes are no-touch returns.