Commit Graph

78 Commits

Author SHA1 Message Date
mitchmindtree 476f6c4c2c Only allow for private construction of `SupportedStreamConfig`.
This should give the user a higher confidence that, if they have a
`SupportedStreamConfig` format type that it is actually supported.

Also updates the `raw` stream builder methods to take a `StreamConfig`
and `SampleFormat` as separate arguments for flexibility.

**Backends Updated**

- [x] null
- [x] alsa
- [ ] emscripten
- [ ] coreaudio
- [ ] wasapi
- [ ] asio
2020-02-02 18:43:30 +01:00
mitchmindtree 9c781bd381 Rename stream `Format` types to `Config`
This implements the changes described at #370.

This commit implements only the `null` and `alsa` backends - the rest
will be implemented in follow-up commits.

Closes #370.
2020-01-27 21:28:07 +01:00
Benjamin Saunders 8d471f3d0e Illustrate alternative structure in beep example 2020-01-21 22:49:31 -08:00
Benjamin Saunders 076b814a15 Introduce polymorphic stream constructors 2020-01-21 22:20:26 -08:00
Benjamin Saunders 78df791377 Add _raw suffix to stream constructors 2020-01-21 21:52:18 -08:00
mitchmindtree aab0d90add Remove old `.rustfmt.toml` config. Run default `cargo fmt` on repo.
Seeing as a few large refactors have landed recently, I thought I'd take
this opportunity to do a `cargo fmt` run and standardise on the default
rustfmt settings.
2020-01-20 20:35:23 +01:00
mitchmindtree 58356f49b4 An alternative approach to removing `UnknownBufferType`.
This is a potential alternative to #359. This PR is based on #359.

This approach opts for a dynamically checked sample type approach with
the aim of minimising compile time and binary size.

You can read more discussion on this [here](https://github.com/RustAudio/cpal/pull/359#issuecomment-575931461)

Implemented backends:

- [x] null
- [x] ALSA
- [ ] CoreAudio
- [ ] WASAPI
- [ ] ASIO
- [ ] Emscripten
2020-01-19 15:06:19 +01:00
mitchmindtree 5a619877f9 Update docs for removal of UnknownTypeBuffer 2020-01-18 15:13:17 +01:00
mitchmindtree 05b62bb1c0 Remove `UnknownTypeBuffer` in favour of specifying sample type.
This is an implementation of the planned changes described in #119.

For a quick overview of how the API has changed, check out the updated
examples.

**TODO:**

- [x] Update API.
- [x] Update examples.
- [ ] Remove `data_type` field from `Format` (see [here](https://github.com/RustAudio/cpal/issues/119#issuecomment-573788380)).
- Update backends:
  - [x] null
  - [x] ALSA
  - [ ] ASIO
  - [ ] WASAPI
  - [ ] CoreAudio
  - [ ] Emscripten

Closes #119
Closes #260
2020-01-18 15:13:17 +01:00
Tatsuyuki Ishi cede7b41db Remove EventLoop and port the ALSA backend 2019-12-31 15:46:10 +01:00
Tatsuyuki Ishi 3cce3e43d9 Change callback interface so that it takes a dedicated error callback 2019-12-31 15:42:35 +01:00
Tatsuyuki Ishi c97d1dd3fa Remove EventLoop and port the ALSA backend 2019-12-31 15:42:35 +01:00
mitchmindtree 7b08cb0dae Update examples for switch to `thiserror`
To compensate for the removal of `failure`'s application friendly
`failure::Error` trait, this `anyhow` crate has been added as a
dev-dependency for the examples, but is by no means a necessity for
other crates downstream of CPAL.
2019-10-13 12:36:49 +02:00
Mitchell Hentges 1676bf20b6
Adds comment about latency-push unwrap() 2019-09-27 10:18:23 -07:00
Mitchell Hentges 624d1f8ce6
Uses ringbuffer in feedback example 2019-09-26 17:19:12 -07:00
Tatsuyuki Ishi 984ff0fd30 Add name to HostId 2019-07-18 09:46:50 +09:00
mitchmindtree 5e4f384992 Refactor `Host` and related traits into a new `traits` module
This is a draft implementation of #294. I'll leave this open for
feedback and potentially better trait naming suggestions or better
solutions in general!

cc @ishitatsuyuki
2019-06-29 14:45:15 +02:00
mitchmindtree e8a05379c2 [WIP] Introduce a `Host` API
This is an implementation of the API described at #204. Please see that
issue for more details on the motivation.

-----

A **Host** provides access to the available audio devices on the system.
Some platforms have more than one host available, e.g.
wasapi/asio/dsound on windows, alsa/pulse/jack on linux and so on. As a
result, some audio devices are only available on certain hosts, while
others are only available on other hosts. Every platform supported by
CPAL has at least one **DefaultHost** that is guaranteed to be available
(alsa, wasapi and coreaudio). Currently, the default hosts are the only
hosts supported by CPAL, however this will change as of landing #221 (cc
@freesig). These changes should also accommodate support for other hosts
such as jack #250 (cc @derekdreery) and pulseaudio (cc @knappador) #259.

This introduces a suite of traits allowing for both compile time and
runtime dispatch of different hosts and their uniquely associated device
and event loop types.

A new private **host** module has been added containing the individual
host implementations, each in their own submodule gated to the platforms
on which they are available.

A new **platform** module has been added containing platform-specific
items, including a dynamically dispatched host type that allows for
easily switching between hosts at runtime.

The **ALL_HOSTS** slice contains a **HostId** for each host supported on
the current platform. The **available_hosts** function produces a
**HostId** for each host that is currently *available* on the platform.
The **host_from_id** function allows for initialising a host from its
associated ID, failing with a **HostUnavailable** error. The
**default_host** function returns the default host and should never
fail.

Please see the examples for a demonstration of the change in usage. For
the most part, things look the same at the surface level, however the
role of device enumeration and creating the event loop have been moved
from global functions to host methods. The enumerate.rs example has been
updated to enumerate all devices for each host, not just the default.

**TODO**

- [x] Add the new **Host** API
- [x] Update examples for the new API.
- [x] ALSA host
- [ ] WASAPI host
- [ ] CoreAudio host
- [ ] Emscripten host **Follow-up PR**
- [ ] ASIO host #221

cc @ishitatsuyuki more to review for you if you're interested, but it
might be easier after #288 lands and this gets rebased.
2019-06-24 21:45:04 +02:00
mitchmindtree c72bafd8ab Update examples eprintln to more accurately reflect error 2019-06-24 21:13:07 +02:00
mitchmindtree c05d2916b1 Remove `StreamEvent` in favour of `StreamDataResult` 2019-06-24 20:43:27 +02:00
mitchmindtree 39cd5d0084 Update examples for addition of new StreamEvent API 2019-06-22 00:10:40 +02:00
mitchmindtree 0b6e66d38e Update examples to use std Termination 2019-06-21 14:55:21 +02:00
mitchmindtree eae0e18714 Add `PlayStreamError` and `PauseStreamError`.
This allows for properly handling potential failure on macOS. We should
also consider propagating the mutex/channel poison errors through these
new types, especially considering the potential removal of the event
loop in favour of switching over to high-priority audio threads on
windows and linux.
2019-06-21 03:04:15 +02:00
mitchmindtree fbb97f51ef Update examples for DeviceNameError 2019-06-21 01:37:55 +02:00
mitchmindtree 42fc702f53 Add `BackendSpecificError`. Add new `DevicesError`.
See the documentation for both new errors for details.

The new `DevicesError` has been added to allow for returning errors when
enumerating devices. This has allowed to remove multiple potential
`panic!`s in each of the alsa, coreaudio and wasapi backends.
2019-06-20 22:37:36 +02:00
Mohanson 6ceb3a215f
Update feedback.rs 2019-06-19 10:34:12 +08:00
mitchmindtree c20978fc01 Add an example that demonstrates feeding input directly to output with some latency 2018-02-17 15:33:00 +11:00
mitchmindtree c38bbb26e4 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

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 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 #117.
Closes #118.

* Update ALSA backend for new `Device` and `Stream` API.

* Update wasapi backend for new `Device` and `Stream` API.

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

* Update coreaudio backend for new `Device` and `Stream` API.

* Fix lib doc tests for Device and Stream API update

* Update emscripten backend for new `Device` and `Stream` API.

* Update null backend for new `Device` and `Stream` API.

* Merge match exprs in beep.rs example

* Add Input variant along with UnknownTypeInputBuffer and InputBuffer

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

* Update emscripten backend for introduction of InputBuffer

* Make InputBuffer inner field an option to call finish in drop

* Update alsa backend for introduction of InputBuffer

* Update wasapi backend for introduction of InputBuffer

* Update coreaudio backend for introduction of InputBuffer

* Update enumerate.rs example to provide more detail about devices

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 #201.

* Add `record_wav.rs` example for demonstrating input streams

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.

* Implement input stream support for coreaudio 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.

* Add `SupportedFormat::cmp_default_heuristics` method

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.

* Implement input stream support for ALSA backend

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.

* Implement input stream support for wasapi backend

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.

* Fix some warnings in the alsa backend

* Update CHANGELOG for introduction of input streams and related items

* Update README to show latest features supported by CPAL

* Simplify beep example using Device::default_output_format

* Remove old commented code from wasapi/stream.rs
2018-02-12 14:10:24 +01:00
mitchmindtree fcc75f4566 Rename `SamplesRate` to `SampleRate` and `ChannelsCount` to `ChannelCount` (#199)
* Rename SamplesRate to SampleRate and samples_rate to sample_rate

* Rename ChannelsCount to ChannelCount

* Update CHANGELOG for SamplesRate and ChannelsCount renaming
2018-02-04 13:02:16 +01:00
mitchmindtree f2728f6bdf Remove unused `ChannelPosition` API (update all backends and examples accordingly) (#198)
* Remove ChannelPosition API

This removes the ChannelPosition API from the lib root and updates the
ALSA backend and examples accordingly. The other backends have not yet
been updated.

Related discussion at #187.

* Update windows backend to removal of ChannelPosition API

The windows backend now assumes the channel position order is equal to
the channel position mask order. E.g. channel 0 will always be front
left, channel 1 will always be front right, etc.

Compiled and ran both examples successfully.

* Update coreaudio backend to removal of ChannelPosition API

Compiled and ran both examples successfully.

* Update emscriptem backend for removal of ChannelPosition API

* Update CHANGELOG for ChannelPosition removal
2018-02-04 10:38:06 +01:00
mitchmindtree 3952c44c63 [macos] Implement Endpoint and Format Enumeration
Based on #195.

Also implements proper handling of the given `Endpoint` in the
macos implementation of the `build_voice` method.

Updates to the latest coreaudio-sys and coreaudio-rs which include the
additional necessary frameworks.

Also adds a line that prints the name of the default device in the
`enumeration.rs` example.

Updates the CHANGELOG for this PR.

Closes #194.
Related to #180.

Related external issues:

- RustAudio/coreaudio-sys#4
- RustAudio/coreaudio-rs#57
2018-01-28 12:40:25 +11:00
tomaka 87949d859b Add SupportedFormat (#168) 2017-10-20 21:18:40 +02:00
jansol 393206bde9 examples: Avoid f32 precision loss in beep example (#167) 2017-10-20 17:12:01 +02:00
tomaka c28407b26d Fix warnings and reduce scope of libc (#166) 2017-10-19 12:44:14 +02:00
tomaka 6ae01f437c RFC: Rework the API [WIP] (#165)
* Rework the API to not use futures anymore

* Add some comments

* Update the MacOS backend

* Restore the null implementation

* Add an emscripten backend

* Remove erroneously added feature

* Fix to_f32 formula

* [WIP] Alsa backend

* Alsa backend compiling

* Working ALSA backend

* Fix tests

* Move WASAPI endpoint to endpoint module

* Fix WASAPI warnings

* Rework the WASAPI backend

* Check overflows for voice ID

* Add comments and minor fixes to WASAPI backend

* Add a changelog
2017-10-18 20:24:05 +02:00
tomaka 2028d5907f Run rustfmt on the code (#162) 2017-10-11 13:24:49 +02:00
tomaka cdcef96279 Remove the `get_` prefix of methods (#151)
* Remove the `get_` prefix of methods

* Fix overlooks
2017-10-11 10:39:44 +02:00
thiolliere f822631bc4 impl play and pause for ALSA
snd_pcm_pause could have been used but not all hardware implement it, so
I propose not to use it.

In this implementation:

there are two kind of scheduling: wait for resume signal and wait for
pcm to be available

if the stream is paused then it return notready and wait for resume

the event loop is different as it manages descriptors corresponding to
voices according to the nature of the scheduling.

there is still a FIXME: in voice.play the is signal is send even if
the event loop wasn't waiting for resume.
It doesn't seem to create any issue. But it happens when you write
voice.pause();voice.play();
2016-10-02 13:29:01 +02:00
thiolliere e031025abe update to futures 0.1.1: alsa wasapi 2016-10-01 00:44:22 +02:00
Pierre Krieger b1add0b12b Fix most warnings 2016-08-12 17:57:06 +02:00
Pierre Krieger be8310da51 Draft for switching to futures 2016-08-02 18:19:03 +02:00
tomaka ec0bd9ebbc Improve error reporting in beep example 2016-01-15 18:05:29 +01:00
Pierre Krieger 5fa41538a6 Various ALSA fixes 2015-09-22 15:46:56 +02:00
Pierre Krieger ec48453b6f Add endpoint::get_name() and an enumerate example 2015-09-22 14:46:27 +02:00
Pierre Krieger 8f11173256 Add an enumerate example 2015-09-22 14:43:30 +02:00
Pierre Krieger 9d56c4c616 Update the beep example 2015-09-10 12:00:52 +02:00
Pierre Krieger 98b931edff Add proper error handling 2015-09-01 14:17:57 +02:00
Pierre Krieger 1985c346ac Add supported formats enumeration 2015-09-01 13:53:54 +02:00
Pierre Krieger 47f966bf75 Correctly enumerate audio devices (core + wasapi) 2015-09-01 11:29:00 +02:00
Pierre Krieger ca72d1d67e Remove the conversion system 2015-08-20 14:44:23 +02:00