Update to a more general Device and Stream API. Add support for input streams (E.g. microphone). Add default format methods. #201

mitchmindtree · 2018-02-04T10:39:09Z

This update prepares for adding input stream support by removing the
Endpoint type (which only supports output streams) in favour of a more
general Device type which may support any number of input or output
streams. Previously discussed at #117.

The name Voice has been replaced with the more ubiquitous name
stream. See #118 for discussion on this.

Also introduces a new StreamData type which is now passed to the
EventLoop::run callback rather than the UnknownTypeBuffer.
StreamData allows for passing either Input data to be read, or
Output data to be written. As of this PR, the Input variant is just
a unit type and is not yet implemented.

All backends have been updated for the API changes, however input
stream functionality remains unimplemented across each backend.
That is, most backend implementations of default_input_device,
supported_input_formats and default_input_format are currently
unimplemented!(); and panic if called. The main aim was to update
to the new API while retaining existing functionality across all backends.

The beep.rs and enumerate.rs examples and the crate-root
documentation have also been updated for the API changes.

Closes #117.
Closes #118.

cc @tomaka (or anyone following CPAL) this is a pretty big change, it would
be great to get your thoughts/feedback on this! I'm totally open to alternative
approaches, this is my attempt at keeping functionality familiar and similar to
the current API while also allowing for input support. I've began implementing
the input API for the coreaudio backend and will be trying to get the remaining
backends implemented over the next couple days too. I don't mind whether
they are a part of this PR or a follow up PR.

EDIT: The new API is now implemented fully across all backends! Emscripten
still needs updating to handle input streams - I'm hoping someone more
familiar with the emscripten tool-chain can do this in a follow-up PR.

tomaka · 2018-02-04T12:08:42Z

examples/beep.rs

+        match data {
+            cpal::StreamData::Output { buffer } => {
+                match buffer {
+                    cpal::UnknownTypeBuffer::U16(mut buffer) => {


Style: this could be merged with the above match (even if that means duplicating the StreamData::Output variant).

tomaka · 2018-02-04T12:09:57Z

src/alsa/enumerate.rs

-/// ALSA implementation for `EndpointsIterator`.
-pub struct EndpointsIterator {
+/// ALSA implementation for `Devices`.
+pub struct Devices {


Should be DevicesIter IMO.

Hmmm I tend to avoid adding the Iter suffix unless I'm trying to avoid ambiguity between a collection and its iterator. IMO Devices is fine in the same way that std::str::Chars is OK.

tomaka · 2018-02-04T12:16:33Z

Thanks! The change is positive. We should probably make sure that the various backends have a working implementation before we ship a version on crates.io.

Please also add entries in CHANGELOG.md!

The enumerate.rs example now also displays: - Supported input stream formats. - Default input stream format. - Default output stream format. This should also be useful for testing the progress of RustAudio#201.

Adds only the necessary cargo features to reduce compile time and reduce the chance of linking errors occurring for unused libraries (e.g. d3d12.dll fails to link on my win10 VM). I thought I'd try and land this before before working on the wasapi backend implementation for RustAudio#201. Tested both beep.rs and enumerate.rs and they work fine with the update.

Adds only the necessary cargo features to reduce compile time and reduce the chance of linking errors occurring for unused libraries (e.g. d3d12.dll fails to link on my win10 VM). I thought I'd try and land this before before working on the wasapi backend implementation for #201. Tested both beep.rs and enumerate.rs and they work fine with the update.

The enumerate.rs example now also displays: - Supported input stream formats. - Default input stream format. - Default output stream format. This should also be useful for testing the progress of RustAudio#201.

This update prepares for adding input stream support by removing the `Endpoint` type (which only supports output streams) in favour of a more general `Device` type which may support any number of input or output streams. Previously discussed at RustAudio#117. The name `Voice` has been replaced with the more ubiquitous name `Stream`. See RustAudio#118 for justification. Also introduces a new `StreamData` which is now passed to the `EventLoop::run` callback rather than the `UnknownTypeBuffer`. `StreamData` allows for passing either `Input` data to be read, or `Output` data to be written. The `beep.rs` example has been updated for the API changes. None of the backends have been updated for this API change yet. Backends will be updated in the following commits. Closes RustAudio#117. Closes RustAudio#118.

UnknownTypeBuffer and Buffer have been renamed to UnknownTypeOutputBuffer and OutputBuffer respectively. No backends have yet been updated for this name change or the addition of the InputBuffer.

The enumerate.rs example now also displays: - Supported input stream formats. - Default input stream format. - Default output stream format. This should also be useful for testing the progress of RustAudio#201.

Records a ~3 second WAV file to `$CARGO_MANIFEST_DIR/recorded.wav` using the default input device and default input format. Uses hound 3.0 to create and write to the WAV file. This should also be useful for testing the input stream implementations for each different cpal backend.

This implements the following for the coreaudio backend: - Device::supported_input_formats - Device::default_input_format - Device::default_output_format - EventLoop::build_input_stream The `enumerate.rs` and `record_wav.rs` examples now work successfully on macos.

This adds a comparison function which compares two `SupportedFormat`s in terms of their priority of use as a default stream format. Some backends (such as ALSA) do not provide a default stream format for their audio devices. In these cases, CPAL attempts to decide on a reasonable default format for the user. To do this we use the "greatest" of all supported stream formats when compared with this method.

This implements the following for the ALSA backend: - Device::supported_input_formats - Device::default_input_format - Device::default_output_format - EventLoop::build_input_stream Note that ALSA itself does not give default stream formats for its devices. Thus the newly added `SupportedFormat::cmp_default_heuristics` method is used to determine the most suitable, supported stream format to use as the default. The `enumerate.rs` and `record_wav.rs` examples now work successfully on my linux machine.

This implements the following for the wasapi backend: - Device::supported_input_formats - Device::default_input_format - Device::default_output_format - EventLoop::build_input_stream Note that wasapi does not enumerate supported input/output stream formats for its devices. Instead, we query the `IsFormatSupported` method for supported formats ourselves.

mitchmindtree · 2018-02-10T12:51:58Z

OK, input streams are now be supported across coreaudio, alsa and wasapi! This includes the Device::default_{input/output}_format, Device::supported_input_formats and Endpoint::build_input_stream methods.

I've fixed the Device::name method on windows (it now uses FriendlyName rather than the GUID). I also updated the run_inner method to handle non-f32 sample formats properly.

I've updated the enumerate example to display both default input/output devices as well as default input/output formats and supported input/output formats for all devices.

I've also added a new record_wav.rs example that records three seconds of audio from the system's default input device and writes this audio to a wav at $CARGO_MANIFEST_DIR/recorded.wav. I used this for testing across all of the main backends.

All three examples work on the macos (10.10), linux and two separate windows 10 systems I've been using for testing, but more testing is welcome of course!

I've also updated the CHANGELOG to account for all changes in this PR.

This PR should now be ready for review!

mitchmindtree · 2018-02-11T02:26:01Z

@freesig could you test this branch (run each of the examples) on your mac and the windows machine while you have it? Also maybe let us know what mac version you're running (i've only tested on 10.10).

freesig · 2018-02-11T05:37:31Z

@mitchmindtree It ran fine on the mac(10.13.3)
Everything worked fine on the windows except record_wav

thread 'main' panicked at 'Failed to get default input device', src\libcore\option.rs:874:4
note: Run with RUST_BACKTRACE=1 for a backtrace.
error: process didn't exit successfully: target\release\examples\record_wav.exe (exit code: 101)

mitchmindtree · 2018-02-11T05:41:30Z

Ahh right, I guess you just don't have any input audio devices on the windows machine then (you can check this with the enumerate example - it should show None for default input device)? Do you have a mic or audio interface that you could use to test it with? All good if not, that behaviour is expected for that example if there's no inputs to record with.

freesig · 2018-02-11T05:49:08Z

Yep record_wav works if I just plug a lead into the computers input.

mitchmindtree · 2018-02-11T05:49:33Z

Nice one, thanks for that!

tomaka

Will merge after nit.
I don't see any obvious mistake, so let's merge.

tomaka · 2018-02-12T12:00:23Z

src/wasapi/stream.rs

+                format_attempt.Format
+            };
+
+            /*


Please remove

mitchmindtree · 2018-02-12T12:20:18Z

Good spot! Fixed.

mitchmindtree force-pushed the device_api branch 2 times, most recently from 9a54a5f to d8e4efb Compare February 4, 2018 12:09

tomaka requested changes Feb 4, 2018

View reviewed changes

mitchmindtree force-pushed the device_api branch from f7af314 to 0e98153 Compare February 6, 2018 05:02

mitchmindtree mentioned this pull request Feb 7, 2018

Update winapi version from 0.2 to 0.3 #202

Merged

mitchmindtree force-pushed the device_api branch from 5f1cdab to ced8b1b Compare February 8, 2018 03:14

mitchmindtree force-pushed the device_api branch from ced8b1b to dc3cef3 Compare February 10, 2018 12:23

mitchmindtree added 17 commits February 10, 2018 23:25

Update ALSA backend for new Device and Stream API.

2b8498e

Update wasapi backend for new Device and Stream API.

f21e3b4

Update enumerate.rs example for new Device and Stream API.

0ffb79c

Update coreaudio backend for new Device and Stream API.

6b90591

Fix lib doc tests for Device and Stream API update

501db49

Update emscripten backend for new Device and Stream API.

c73230f

Update null backend for new Device and Stream API.

0304e88

Merge match exprs in beep.rs example

efc4ee1

Add Input variant along with UnknownTypeInputBuffer and InputBuffer

502fd6a

UnknownTypeBuffer and Buffer have been renamed to UnknownTypeOutputBuffer and OutputBuffer respectively. No backends have yet been updated for this name change or the addition of the InputBuffer.

Update null backend for introduction of InputBuffer

9f797cd

Update emscripten backend for introduction of InputBuffer

9eb4ecc

Make InputBuffer inner field an option to call finish in drop

9057fd0

Update alsa backend for introduction of InputBuffer

5ce27e0

Update wasapi backend for introduction of InputBuffer

fbc0aca

Update coreaudio backend for introduction of InputBuffer

a7b3f88

Update enumerate.rs example to provide more detail about devices

b07a545

The enumerate.rs example now also displays: - Supported input stream formats. - Default input stream format. - Default output stream format. This should also be useful for testing the progress of RustAudio#201.

mitchmindtree added 5 commits February 10, 2018 23:25

mitchmindtree force-pushed the device_api branch from dc3cef3 to 5c7b0cf Compare February 10, 2018 12:26

mitchmindtree added 2 commits February 10, 2018 23:44

Fix some warnings in the alsa backend

64d509b

Update CHANGELOG for introduction of input streams and related items

525c0b8

mitchmindtree changed the title ~~Update to a more general Device and Stream API (preparing for Input stream support)~~ Update to a more general Device and Stream API. Add support for input streams (E.g. microphone). Add default format methods. Feb 10, 2018

mitchmindtree force-pushed the device_api branch 2 times, most recently from a1b6b25 to edb040d Compare February 11, 2018 03:12

Update README to show latest features supported by CPAL

2287724

mitchmindtree force-pushed the device_api branch from edb040d to 2287724 Compare February 11, 2018 03:13

Simplify beep example using Device::default_output_format

f52369c

tomaka approved these changes Feb 12, 2018

View reviewed changes

tomaka requested changes Feb 12, 2018

View reviewed changes

src/wasapi/stream.rs Outdated

format_attempt.Format

};

/*

Copy link

Collaborator

tomaka Feb 12, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please remove

Remove old commented code from wasapi/stream.rs

4629afb

tomaka approved these changes Feb 12, 2018

View reviewed changes

tomaka merged commit c38bbb2 into RustAudio:master Feb 12, 2018

This was referenced Feb 12, 2018

Support Input, Output and Duplex stream types #116

Closed

Panic when running example on window 10 #111

Closed

mitchmindtree deleted the device_api branch February 12, 2018 14:54

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update to a more general Device and Stream API. Add support for input streams (E.g. microphone). Add default format methods. #201

Update to a more general Device and Stream API. Add support for input streams (E.g. microphone). Add default format methods. #201

mitchmindtree commented Feb 4, 2018 •

edited

Loading

tomaka Feb 4, 2018

tomaka Feb 4, 2018

mitchmindtree Feb 10, 2018

tomaka commented Feb 4, 2018

mitchmindtree commented Feb 10, 2018 •

edited

Loading

mitchmindtree commented Feb 11, 2018

freesig commented Feb 11, 2018

mitchmindtree commented Feb 11, 2018

freesig commented Feb 11, 2018

mitchmindtree commented Feb 11, 2018

tomaka left a comment

tomaka Feb 12, 2018

mitchmindtree commented Feb 12, 2018

Update to a more general Device and Stream API. Add support for input streams (E.g. microphone). Add default format methods. #201

Update to a more general Device and Stream API. Add support for input streams (E.g. microphone). Add default format methods. #201

Conversation

mitchmindtree commented Feb 4, 2018 • edited Loading

tomaka Feb 4, 2018

Choose a reason for hiding this comment

tomaka Feb 4, 2018

Choose a reason for hiding this comment

mitchmindtree Feb 10, 2018

Choose a reason for hiding this comment

tomaka commented Feb 4, 2018

mitchmindtree commented Feb 10, 2018 • edited Loading

mitchmindtree commented Feb 11, 2018

freesig commented Feb 11, 2018

mitchmindtree commented Feb 11, 2018

freesig commented Feb 11, 2018

mitchmindtree commented Feb 11, 2018

tomaka left a comment

Choose a reason for hiding this comment

tomaka Feb 12, 2018

Choose a reason for hiding this comment

mitchmindtree commented Feb 12, 2018

mitchmindtree commented Feb 4, 2018 •

edited

Loading

mitchmindtree commented Feb 10, 2018 •

edited

Loading