Feature: Adding support for retrieval of ASIO channel names - 0.3.1 - #1303
Open
SpruceCloud wants to merge 4 commits into
Open
Feature: Adding support for retrieval of ASIO channel names - 0.3.1#1303SpruceCloud wants to merge 4 commits into
SpruceCloud wants to merge 4 commits into
Conversation
An ASIO driver names its channels, and for aggregating drivers such as
ASIO4ALL — which concatenates the channels of whichever WDM devices are
enabled in its control panel — those names are the only stable way to map
a channel index to physical hardware. The channel count and ordering can
change between sessions, so a host that persists "output channels 4 and 5"
may address a different pair of speakers on the next launch.
`asio-sys` already called `ASIOGetChannelInfo`, but only privately, and
`stream_data_type` discarded everything but channel 0's sample type.
Add `ChannelInfo` plus `input_channel_info`, `output_channel_info`,
`input_channel_infos` and `output_channel_infos` on `Driver`, whose
existence already proves the driver is loaded and initialised. Index bounds
are checked before calling into the SDK, since drivers are not required to
validate them. `sample_type` is an `Option` rather than reusing
`stream_data_type`'s `expect`, so an unfamiliar format enum cannot panic a
name lookup.
Purely additive: no signature or behaviour changes to existing items.
Verified with `cargo run --example enumerate` against ASIO4ALL v2, which
reports the underlying WDM pin names ("HD Audio output 1", ...).
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Bump `asio-sys` to 0.3.1 for the additive `ChannelInfo` API, update cpal's dependency lower bound to match, and record the change in the changelog. Use `i32` rather than `c_long` in the new public signatures, matching the convention adopted for the rest of the public surface in 0.3.0. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
`channel` and `isInput` are inputs to `ASIOGetChannelInfo`: the caller sets
them and the driver fills in the rest. Nothing obliges a driver to leave them
intact, so a driver that memsets the struct would have made every entry of
`input_channel_infos()` report `channel: 0, is_input: false` — destroying the
index-to-hardware mapping the API exists to provide. Report the values we
asked for instead; only `isActive` is now read back from the driver.
Mark `ChannelInfo` `#[non_exhaustive]`: it mirrors a C struct that may grow,
and callers only ever read it.
The name is decoded from the system code page as UTF-8, so every non-ASCII
byte becomes U+FFFD and two names differing only in such bytes decode alike.
Doing it properly needs `MultiByteToWideChar` and hence a Windows API
dependency this crate does not have, so document the caveat on the field
rather than claiming, as the comment did, that the cost is a stray character.
Also note on the singular accessors that they query the channel count too
(prefer the plural form in a loop) and that `InvalidInput` is indistinguishable
from the driver rejecting the parameter itself, add the missing `[0.3.1]`
changelog link reference, and stop printing the example's `<unnamed>`
placeholder through `{:?}`, where it looked like a real channel name.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Selecting "output channels 4 and 5" is only meaningful if the host can say what those channels are. cpal exposed a channel *count* and nothing else, so an application building a channel picker had no labels to show and no stable handle to persist a selection against. Add `ChannelDescription` — an optional driver-supplied `name` and an optional `ChannelPosition` — returned by `DeviceTrait::input_channel_descriptions()` and `output_channel_descriptions()`. Both fields are optional and independent because the backends split cleanly: ASIO names channels but knows no speaker layout, WASAPI reports a layout but no names. `descriptions[i]` describes interleaved offset `i` of a stream built on the device. A host that cannot guarantee that alignment returns an empty `Vec` rather than a best guess: a label that does not match the buffer index it appears to describe is worse than no label. The default implementation returns an empty `Vec`, so custom hosts and the backends that have nothing to report are unaffected. `ChannelPosition` mirrors the WAVE `dwChannelMask` positions, which CoreAudio's `AudioChannelLabel` and ALSA's channel maps also map onto, so the enum should not need to grow when further backends are wired up. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.