2017-10-23 14:41:38 +00:00
|
|
|
//! # How to use cpal
|
|
|
|
//!
|
|
|
|
//! Here are some concepts cpal exposes:
|
|
|
|
//!
|
2019-12-23 03:22:35 +00:00
|
|
|
//! - A [**Host**](./struct.Host.html) provides access to the available audio devices on the system.
|
[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-23 13:49:48 +00:00
|
|
|
//! Some platforms have more than one host available, but every platform supported by CPAL has at
|
2019-12-23 03:22:35 +00:00
|
|
|
//! least one [**DefaultHost**](./struct.Host.html) that is guaranteed to be available.
|
|
|
|
//! - A [**Device**](./struct.Device.html) is an audio device that may have any number of input and
|
[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-23 13:49:48 +00:00
|
|
|
//! output streams.
|
2019-12-14 16:30:25 +00:00
|
|
|
//! - A [**Stream**](./trait.Stream.html) is an open flow of audio data. Input streams allow you to
|
|
|
|
//! receive audio data, output streams allow you to play audio data. You must choose which
|
|
|
|
//! **Device** will run your stream before you can create one. Often, a default device can be
|
|
|
|
//! retrieved via the **Host**.
|
2017-10-23 14:41:38 +00:00
|
|
|
//!
|
2019-12-14 16:30:25 +00:00
|
|
|
//! The first step is to initialise the `Host`:
|
2017-10-23 14:41:38 +00:00
|
|
|
//!
|
|
|
|
//! ```
|
2019-06-28 21:42:07 +00:00
|
|
|
//! use cpal::traits::HostTrait;
|
[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-23 13:49:48 +00:00
|
|
|
//! let host = cpal::default_host();
|
2017-10-23 14:41:38 +00:00
|
|
|
//! ```
|
|
|
|
//!
|
2019-12-14 16:30:25 +00:00
|
|
|
//! Then choose an available `Device`. The easiest way is to use the default input or output
|
|
|
|
//! `Device` via the `default_input_device()` or `default_output_device()` functions. Alternatively
|
|
|
|
//! you can enumerate all the available devices with the `devices()` function. Beware that the
|
2018-02-12 13:10:24 +00:00
|
|
|
//! `default_*_device()` functions return an `Option` in case no device is available for that
|
|
|
|
//! stream type on the system.
|
2017-10-23 14:41:38 +00:00
|
|
|
//!
|
2019-06-21 13:57:15 +00:00
|
|
|
//! ```no_run
|
2019-06-28 21:42:07 +00:00
|
|
|
//! # use cpal::traits::HostTrait;
|
[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-23 13:49:48 +00:00
|
|
|
//! # let host = cpal::default_host();
|
|
|
|
//! let device = host.default_output_device().expect("no output device available");
|
2017-10-23 14:41:38 +00:00
|
|
|
//! ```
|
|
|
|
//!
|
2018-02-12 13:10:24 +00:00
|
|
|
//! Before we can create a stream, we must decide what the format of the audio samples is going to
|
|
|
|
//! be. You can query all the supported formats with the `supported_input_formats()` and
|
|
|
|
//! `supported_output_formats()` methods. These produce a list of `SupportedFormat` structs which
|
|
|
|
//! can later be turned into actual `Format` structs. If you don't want to query the list of
|
|
|
|
//! formats, you can also build your own `Format` manually, but doing so could lead to an error
|
|
|
|
//! when building the stream if the format is not supported by the device.
|
2017-10-23 14:41:38 +00:00
|
|
|
//!
|
|
|
|
//! > **Note**: the `supported_formats()` method could return an error for example if the device
|
|
|
|
//! > has been disconnected.
|
|
|
|
//!
|
|
|
|
//! ```no_run
|
2019-06-28 21:42:07 +00:00
|
|
|
//! use cpal::traits::{DeviceTrait, HostTrait};
|
[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-23 13:49:48 +00:00
|
|
|
//! # let host = cpal::default_host();
|
|
|
|
//! # let device = host.default_output_device().unwrap();
|
2018-02-12 13:10:24 +00:00
|
|
|
//! let mut supported_formats_range = device.supported_output_formats()
|
|
|
|
//! .expect("error while querying formats");
|
|
|
|
//! let format = supported_formats_range.next()
|
|
|
|
//! .expect("no supported format?!")
|
|
|
|
//! .with_max_sample_rate();
|
2017-10-23 14:41:38 +00:00
|
|
|
//! ```
|
|
|
|
//!
|
2019-12-14 16:30:25 +00:00
|
|
|
//! Now that we have everything for the stream, we are ready to create it from our selected device:
|
2017-10-23 14:41:38 +00:00
|
|
|
//!
|
|
|
|
//! ```no_run
|
2019-12-14 16:30:25 +00:00
|
|
|
//! use cpal::traits::{DeviceTrait, HostTrait, StreamTrait};
|
[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-23 13:49:48 +00:00
|
|
|
//! # let host = cpal::default_host();
|
|
|
|
//! # let device = host.default_output_device().unwrap();
|
2019-12-14 16:30:25 +00:00
|
|
|
//! # let format = device.default_output_format().unwrap();
|
|
|
|
//! let stream = device.build_output_stream(
|
|
|
|
//! &format,
|
|
|
|
//! move |data| {
|
|
|
|
//! // react to stream events and read or write stream data here.
|
|
|
|
//! },
|
|
|
|
//! move |err| {
|
|
|
|
//! // react to errors here.
|
|
|
|
//! },
|
|
|
|
//! );
|
2017-10-23 14:41:38 +00:00
|
|
|
//! ```
|
|
|
|
//!
|
2019-12-14 16:30:25 +00:00
|
|
|
//! While the stream is running, the selected audio device will periodically call the data callback
|
|
|
|
//! that was passed to the function. The callback is passed an instance of type `StreamData` that
|
|
|
|
//! represents the data that must be read from or written to. The inner `UnknownTypeOutputBuffer`
|
|
|
|
//! can be one of `I16`, `U16` or `F32` depending on the format that was passed to
|
|
|
|
//! `build_output_stream`.
|
2017-10-23 14:41:38 +00:00
|
|
|
//!
|
2019-12-14 16:30:25 +00:00
|
|
|
//! > **Note**: Creating and running a stream will *not* block the thread. On modern platforms, the
|
|
|
|
//! > given callback is called by a dedicated, high-priority thread responsible for delivering
|
|
|
|
//! > audio data to the system's audio device in a timely manner. On older platforms that only
|
|
|
|
//! > provide a blocking API (e.g. ALSA), CPAL will create a thread in order to consistently
|
2019-12-31 15:02:08 +00:00
|
|
|
//! > provide non-blocking behaviour (currently this is a thread per stream, but this may change to
|
|
|
|
//! > use a single thread for all streams). *If this is an issue for your platform or design,
|
|
|
|
//! > please share your issue and use-case with the CPAL team on the github issue tracker for
|
2019-12-14 16:30:25 +00:00
|
|
|
//! > consideration.*
|
|
|
|
//!
|
|
|
|
//! In this example, we simply fill the given output buffer with zeroes.
|
2017-10-23 14:41:38 +00:00
|
|
|
//!
|
2019-06-21 13:57:15 +00:00
|
|
|
//! ```no_run
|
2019-12-14 16:30:25 +00:00
|
|
|
//! use cpal::{StreamData, UnknownTypeOutputBuffer};
|
|
|
|
//! use cpal::traits::{DeviceTrait, HostTrait, StreamTrait};
|
[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-23 13:49:48 +00:00
|
|
|
//! # let host = cpal::default_host();
|
2019-12-14 16:30:25 +00:00
|
|
|
//! # let device = host.default_output_device().unwrap();
|
|
|
|
//! # let format = device.default_output_format().unwrap();
|
|
|
|
//! let stream = device.build_output_stream(
|
|
|
|
//! &format,
|
|
|
|
//! move |data| {
|
|
|
|
//! match data {
|
|
|
|
//! StreamData::Output { buffer: UnknownTypeOutputBuffer::U16(mut buffer) } => {
|
|
|
|
//! for elem in buffer.iter_mut() {
|
|
|
|
//! *elem = u16::max_value() / 2;
|
|
|
|
//! }
|
|
|
|
//! },
|
|
|
|
//! StreamData::Output { buffer: UnknownTypeOutputBuffer::I16(mut buffer) } => {
|
|
|
|
//! for elem in buffer.iter_mut() {
|
|
|
|
//! *elem = 0;
|
|
|
|
//! }
|
|
|
|
//! },
|
|
|
|
//! StreamData::Output { buffer: UnknownTypeOutputBuffer::F32(mut buffer) } => {
|
|
|
|
//! for elem in buffer.iter_mut() {
|
|
|
|
//! *elem = 0.0;
|
|
|
|
//! }
|
|
|
|
//! },
|
|
|
|
//! _ => (),
|
|
|
|
//! }
|
|
|
|
//! },
|
|
|
|
//! move |err| {
|
|
|
|
//! eprintln!("an error occurred on the output audio stream: {}", err);
|
|
|
|
//! },
|
|
|
|
//! );
|
2017-10-23 14:41:38 +00:00
|
|
|
//! ```
|
|
|
|
//!
|
2019-12-14 16:30:25 +00:00
|
|
|
//! Not all platforms automatically run the stream upon creation. To ensure the stream has started,
|
|
|
|
//! we can use `Stream::play`.
|
2017-10-23 14:41:38 +00:00
|
|
|
//!
|
|
|
|
//! ```no_run
|
2019-12-14 16:30:25 +00:00
|
|
|
//! # use cpal::traits::{DeviceTrait, HostTrait, StreamTrait};
|
[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-23 13:49:48 +00:00
|
|
|
//! # let host = cpal::default_host();
|
2019-12-14 16:30:25 +00:00
|
|
|
//! # let device = host.default_output_device().unwrap();
|
|
|
|
//! # let format = device.default_output_format().unwrap();
|
|
|
|
//! # let stream = device.build_output_stream(&format, move |_data| {}, move |_err| {}).unwrap();
|
|
|
|
//! stream.play().unwrap();
|
2017-10-23 14:41:38 +00:00
|
|
|
//! ```
|
|
|
|
//!
|
2019-12-14 16:30:25 +00:00
|
|
|
//! Some devices support pausing the audio stream. This can be useful for saving energy in moments
|
|
|
|
//! of silence.
|
2017-10-23 14:41:38 +00:00
|
|
|
//!
|
|
|
|
//! ```no_run
|
2019-12-14 16:30:25 +00:00
|
|
|
//! # use cpal::traits::{DeviceTrait, HostTrait, StreamTrait};
|
[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-23 13:49:48 +00:00
|
|
|
//! # let host = cpal::default_host();
|
2019-12-14 16:30:25 +00:00
|
|
|
//! # let device = host.default_output_device().unwrap();
|
|
|
|
//! # let format = device.default_output_format().unwrap();
|
|
|
|
//! # let stream = device.build_output_stream(&format, move |_data| {}, move |_err| {}).unwrap();
|
|
|
|
//! stream.pause().unwrap();
|
2020-01-13 14:27:41 +00:00
|
|
|
//! ```
|
2016-08-02 14:13:59 +00:00
|
|
|
|
2017-10-22 12:17:25 +00:00
|
|
|
#![recursion_limit = "512"]
|
|
|
|
|
2017-11-03 09:51:02 +00:00
|
|
|
#[cfg(target_os = "windows")]
|
2015-09-01 09:23:41 +00:00
|
|
|
#[macro_use]
|
|
|
|
extern crate lazy_static;
|
2017-10-22 12:17:25 +00:00
|
|
|
// Extern crate declarations with `#[macro_use]` must unfortunately be at crate root.
|
|
|
|
#[cfg(target_os = "emscripten")]
|
|
|
|
#[macro_use]
|
|
|
|
extern crate stdweb;
|
2019-10-13 10:07:49 +00:00
|
|
|
extern crate thiserror;
|
2017-10-22 12:17:25 +00:00
|
|
|
|
2019-09-29 12:05:06 +00:00
|
|
|
pub use error::*;
|
2019-06-28 21:42:07 +00:00
|
|
|
pub use platform::{
|
2019-07-09 06:47:33 +00:00
|
|
|
ALL_HOSTS, available_hosts, default_host, Device, Devices, Host, host_from_id,
|
|
|
|
HostId, Stream, SupportedInputFormats, SupportedOutputFormats,
|
2019-06-28 21:42:07 +00:00
|
|
|
};
|
2017-10-11 11:24:49 +00:00
|
|
|
pub use samples_formats::{Sample, SampleFormat};
|
2015-01-05 09:52:59 +00:00
|
|
|
use std::ops::{Deref, DerefMut};
|
|
|
|
|
2019-09-29 12:05:06 +00:00
|
|
|
mod error;
|
[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-23 13:49:48 +00:00
|
|
|
mod host;
|
|
|
|
pub mod platform;
|
2014-12-17 07:47:19 +00:00
|
|
|
mod samples_formats;
|
2019-06-28 21:42:07 +00:00
|
|
|
pub mod traits;
|
[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-23 13:49:48 +00:00
|
|
|
|
|
|
|
/// A host's device iterator yielding only *input* devices.
|
|
|
|
pub type InputDevices<I> = std::iter::Filter<I, fn(&<I as Iterator>::Item) -> bool>;
|
|
|
|
|
|
|
|
/// A host's device iterator yielding only *output* devices.
|
|
|
|
pub type OutputDevices<I> = std::iter::Filter<I, fn(&<I as Iterator>::Item) -> bool>;
|
2015-09-01 09:23:41 +00:00
|
|
|
|
2018-02-12 13:10:24 +00:00
|
|
|
/// Number of channels.
|
|
|
|
pub type ChannelCount = u16;
|
|
|
|
|
|
|
|
/// The number of samples processed per second for a single channel of audio.
|
|
|
|
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
|
|
|
|
pub struct SampleRate(pub u32);
|
|
|
|
|
|
|
|
/// The format of an input or output audio stream.
|
|
|
|
#[derive(Debug, Clone, PartialEq, Eq)]
|
|
|
|
pub struct Format {
|
|
|
|
pub channels: ChannelCount,
|
|
|
|
pub sample_rate: SampleRate,
|
|
|
|
pub data_type: SampleFormat,
|
|
|
|
}
|
|
|
|
|
|
|
|
/// Describes a range of supported stream formats.
|
|
|
|
#[derive(Debug, Clone, PartialEq, Eq)]
|
|
|
|
pub struct SupportedFormat {
|
|
|
|
pub channels: ChannelCount,
|
|
|
|
/// Minimum value for the samples rate of the supported formats.
|
|
|
|
pub min_sample_rate: SampleRate,
|
|
|
|
/// Maximum value for the samples rate of the supported formats.
|
|
|
|
pub max_sample_rate: SampleRate,
|
|
|
|
/// Type of data expected by the device.
|
|
|
|
pub data_type: SampleFormat,
|
2015-09-01 09:23:41 +00:00
|
|
|
}
|
|
|
|
|
2018-02-12 13:10:24 +00:00
|
|
|
/// Represents a buffer containing audio data that may be read.
|
2017-10-23 14:41:38 +00:00
|
|
|
///
|
2018-02-12 13:10:24 +00:00
|
|
|
/// This struct implements the `Deref` trait targeting `[T]`. Therefore this buffer can be read the
|
|
|
|
/// same way as reading from a `Vec` or any other kind of Rust array.
|
|
|
|
// TODO: explain audio stuff in general
|
2020-01-13 14:27:41 +00:00
|
|
|
// TODO: Consider making this an `enum` with `Interleaved` and `NonInterleaved` variants.
|
2019-10-04 16:18:18 +00:00
|
|
|
#[derive(Debug)]
|
2020-01-13 14:27:41 +00:00
|
|
|
pub struct InputData<'a, T: 'a>
|
2018-02-12 13:10:24 +00:00
|
|
|
where
|
|
|
|
T: Sample,
|
|
|
|
{
|
2019-04-30 06:43:47 +00:00
|
|
|
buffer: &'a [T],
|
2017-10-11 08:39:44 +00:00
|
|
|
}
|
|
|
|
|
2019-04-30 06:43:47 +00:00
|
|
|
/// Represents a buffer that must be filled with audio data. The buffer in unfilled state may
|
|
|
|
/// contain garbage values.
|
2018-02-12 13:10:24 +00:00
|
|
|
///
|
|
|
|
/// This struct implements the `Deref` and `DerefMut` traits to `[T]`. Therefore writing to this
|
|
|
|
/// buffer is done in the same way as writing to a `Vec` or any other kind of Rust array.
|
|
|
|
// TODO: explain audio stuff in general
|
2020-01-13 14:27:41 +00:00
|
|
|
// TODO: Consider making this an `enum` with `Interleaved` and `NonInterleaved` variants.
|
2018-02-12 13:10:24 +00:00
|
|
|
#[must_use]
|
2019-10-04 16:18:18 +00:00
|
|
|
#[derive(Debug)]
|
2020-01-13 14:27:41 +00:00
|
|
|
pub struct OutputData<'a, T: 'a>
|
2018-02-12 13:10:24 +00:00
|
|
|
where
|
|
|
|
T: Sample,
|
|
|
|
{
|
2019-04-30 06:43:47 +00:00
|
|
|
buffer: &'a mut [T],
|
2015-09-01 09:23:41 +00:00
|
|
|
}
|
|
|
|
|
2018-02-12 13:10:24 +00:00
|
|
|
impl SupportedFormat {
|
|
|
|
/// Turns this `SupportedFormat` into a `Format` corresponding to the maximum samples rate.
|
2017-10-18 18:24:05 +00:00
|
|
|
#[inline]
|
2018-02-12 13:10:24 +00:00
|
|
|
pub fn with_max_sample_rate(self) -> Format {
|
|
|
|
Format {
|
|
|
|
channels: self.channels,
|
|
|
|
sample_rate: self.max_sample_rate,
|
|
|
|
data_type: self.data_type,
|
|
|
|
}
|
2017-10-18 18:24:05 +00:00
|
|
|
}
|
|
|
|
|
2018-02-12 13:10:24 +00:00
|
|
|
/// A comparison function which compares two `SupportedFormat`s in terms of their priority of
|
|
|
|
/// use as a default stream format.
|
2017-10-18 18:24:05 +00:00
|
|
|
///
|
2018-02-12 13:10:24 +00:00
|
|
|
/// Some backends 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.
|
2017-10-18 18:24:05 +00:00
|
|
|
///
|
2018-02-12 13:10:24 +00:00
|
|
|
/// Formats are prioritised by the following heuristics:
|
2017-10-18 18:24:05 +00:00
|
|
|
///
|
2018-02-12 13:10:24 +00:00
|
|
|
/// **Channels**:
|
|
|
|
///
|
|
|
|
/// - Stereo
|
|
|
|
/// - Mono
|
|
|
|
/// - Max available channels
|
2017-10-18 18:24:05 +00:00
|
|
|
///
|
2018-02-12 13:10:24 +00:00
|
|
|
/// **Sample format**:
|
|
|
|
/// - f32
|
|
|
|
/// - i16
|
|
|
|
/// - u16
|
2017-10-18 18:24:05 +00:00
|
|
|
///
|
2018-02-12 13:10:24 +00:00
|
|
|
/// **Sample rate**:
|
|
|
|
///
|
|
|
|
/// - 44100 (cd quality)
|
|
|
|
/// - Max sample rate
|
|
|
|
pub fn cmp_default_heuristics(&self, other: &Self) -> std::cmp::Ordering {
|
|
|
|
use std::cmp::Ordering::Equal;
|
|
|
|
use SampleFormat::{F32, I16, U16};
|
|
|
|
|
|
|
|
let cmp_stereo = (self.channels == 2).cmp(&(other.channels == 2));
|
|
|
|
if cmp_stereo != Equal {
|
|
|
|
return cmp_stereo;
|
|
|
|
}
|
|
|
|
|
|
|
|
let cmp_mono = (self.channels == 1).cmp(&(other.channels == 1));
|
|
|
|
if cmp_mono != Equal {
|
|
|
|
return cmp_mono;
|
|
|
|
}
|
|
|
|
|
|
|
|
let cmp_channels = self.channels.cmp(&other.channels);
|
|
|
|
if cmp_channels != Equal {
|
|
|
|
return cmp_channels;
|
|
|
|
}
|
|
|
|
|
|
|
|
let cmp_f32 = (self.data_type == F32).cmp(&(other.data_type == F32));
|
|
|
|
if cmp_f32 != Equal {
|
|
|
|
return cmp_f32;
|
|
|
|
}
|
|
|
|
|
|
|
|
let cmp_i16 = (self.data_type == I16).cmp(&(other.data_type == I16));
|
|
|
|
if cmp_i16 != Equal {
|
|
|
|
return cmp_i16;
|
|
|
|
}
|
|
|
|
|
|
|
|
let cmp_u16 = (self.data_type == U16).cmp(&(other.data_type == U16));
|
|
|
|
if cmp_u16 != Equal {
|
|
|
|
return cmp_u16;
|
|
|
|
}
|
|
|
|
|
|
|
|
const HZ_44100: SampleRate = SampleRate(44_100);
|
|
|
|
let r44100_in_self = self.min_sample_rate <= HZ_44100
|
|
|
|
&& HZ_44100 <= self.max_sample_rate;
|
|
|
|
let r44100_in_other = other.min_sample_rate <= HZ_44100
|
|
|
|
&& HZ_44100 <= other.max_sample_rate;
|
|
|
|
let cmp_r44100 = r44100_in_self.cmp(&r44100_in_other);
|
|
|
|
if cmp_r44100 != Equal {
|
|
|
|
return cmp_r44100;
|
|
|
|
}
|
|
|
|
|
|
|
|
self.max_sample_rate.cmp(&other.max_sample_rate)
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
2020-01-13 14:27:41 +00:00
|
|
|
impl<'a, T> Deref for InputData<'a, T>
|
|
|
|
where
|
|
|
|
T: Sample,
|
2018-02-12 13:10:24 +00:00
|
|
|
{
|
|
|
|
type Target = [T];
|
|
|
|
|
2017-10-18 18:24:05 +00:00
|
|
|
#[inline]
|
2018-02-12 13:10:24 +00:00
|
|
|
fn deref(&self) -> &[T] {
|
2019-04-30 06:43:47 +00:00
|
|
|
self.buffer
|
2018-02-12 13:10:24 +00:00
|
|
|
}
|
|
|
|
}
|
2017-10-18 18:24:05 +00:00
|
|
|
|
2020-01-13 14:27:41 +00:00
|
|
|
impl<'a, T> Deref for OutputData<'a, T>
|
|
|
|
where
|
|
|
|
T: Sample,
|
2018-02-12 13:10:24 +00:00
|
|
|
{
|
|
|
|
type Target = [T];
|
|
|
|
|
|
|
|
#[inline]
|
|
|
|
fn deref(&self) -> &[T] {
|
2019-06-07 19:05:14 +00:00
|
|
|
self.buffer
|
2018-02-12 13:10:24 +00:00
|
|
|
}
|
|
|
|
}
|
|
|
|
|
2020-01-13 14:27:41 +00:00
|
|
|
impl<'a, T> DerefMut for OutputData<'a, T>
|
|
|
|
where
|
|
|
|
T: Sample,
|
2018-02-12 13:10:24 +00:00
|
|
|
{
|
|
|
|
#[inline]
|
|
|
|
fn deref_mut(&mut self) -> &mut [T] {
|
2019-04-30 06:43:47 +00:00
|
|
|
self.buffer
|
2018-02-12 13:10:24 +00:00
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
impl From<Format> for SupportedFormat {
|
|
|
|
#[inline]
|
|
|
|
fn from(format: Format) -> SupportedFormat {
|
|
|
|
SupportedFormat {
|
|
|
|
channels: format.channels,
|
|
|
|
min_sample_rate: format.sample_rate,
|
|
|
|
max_sample_rate: format.sample_rate,
|
|
|
|
data_type: format.data_type,
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
// If a backend does not provide an API for retrieving supported formats, we query it with a bunch
|
|
|
|
// of commonly used rates. This is always the case for wasapi and is sometimes the case for alsa.
|
|
|
|
//
|
|
|
|
// If a rate you desire is missing from this list, feel free to add it!
|
|
|
|
#[cfg(target_os = "windows")]
|
|
|
|
const COMMON_SAMPLE_RATES: &'static [SampleRate] = &[
|
|
|
|
SampleRate(5512),
|
|
|
|
SampleRate(8000),
|
|
|
|
SampleRate(11025),
|
|
|
|
SampleRate(16000),
|
|
|
|
SampleRate(22050),
|
|
|
|
SampleRate(32000),
|
|
|
|
SampleRate(44100),
|
|
|
|
SampleRate(48000),
|
|
|
|
SampleRate(64000),
|
|
|
|
SampleRate(88200),
|
|
|
|
SampleRate(96000),
|
|
|
|
SampleRate(176400),
|
|
|
|
SampleRate(192000),
|
|
|
|
];
|