Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

cubeb.h: Document device switching policy. #582

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

cubeb.h: Document device switching policy. #582

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions include/cubeb/cubeb.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -482,6 +482,21 @@ CUBEB_EXPORT int cubeb_get_preferred_sample_rate(cubeb * context, uint32_t * rat
CUBEB_EXPORT void cubeb_destroy(cubeb * context);

/** Initialize a stream associated with the supplied application context.

@note A NULL @p output_device or @p input_device will cause cubeb to use
the OS default device for that direction. In this case, cubeb will
automatically switch to a new OS default if a device change is detected.
To disable automatic switching, set @ref
CUBEB_STREAM_PREF_DISABLE_DEVICE_SWITCHING on @ref
cubeb_stream_params.prefs.

@note If @p output_device or @p input_device is a valid non-NULL @ref
Copy link
Member

Choose a reason for hiding this comment

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

The output_device selection isn't supported in audiounit-rust yet. @padenot : Do we have a plan to support that? (however, the test might be ready here)

Copy link
Member

Choose a reason for hiding this comment

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

Ah, it seems we do support output_device selection, but I never tested it.

If the stream needs to be reinitialize to default output device when the specified output_device is no longer available, then we do need to listen kAudioDevicePropertyDeviceIsAlive for output device like what we do for the input side.

On the other hand, if the stream using the specified output_device doesn't need to be reinitialized when the specified output_device is no longer available, it seems audiounit-rust meets the spec here.

Anyway, my problem is: what is the intended behavior when the specified output_device or input_device is unplugged while they are being used by some active streams?

Copy link
Collaborator

Choose a reason for hiding this comment

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

Anyway, my problem is: what is the intended behavior when the specified output_device or input_device is unplugged while they are being used by some active streams?

This is in flux at the minute. The current behaviour we want in gecko:

  • If a output device has been opened with an explicit device or a default device, and is no longer available, switch to the new default device
  • If an input device has been opened, it's always with an explicit ID. It it is not available anymore, turn this stream into a output-only stream

When @achronop finishes setSinkId, we'll reevaluate this (or as part of his effort).

I had a design a long time ago that would allow enough flexibility to implement whatever we need: https://github.com/kinetiknz/cubeb/issues/167. I think it still works

Copy link
Collaborator

Choose a reason for hiding this comment

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

I think in general the behaviour @kinetiknz documents here is simpler and works just as well.

Copy link
Contributor

Choose a reason for hiding this comment

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

If a output device has been opened with an explicit device or a default device, and is no longer available, switch to the new default device

If I am not missing something the output device is always non-explicit at the moment in Gecko so @kinetiknz 's document covers our needs. This will be changed when sinkId is in place but we can re-evaluate then. I have already some thoughts about it.

Copy link
Member

Choose a reason for hiding this comment

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

I think my question is here:

If @p output_device or @p input_device is a valid non-NULL @ref cubeb_devid, cubeb will only ever use the specified device and never follow device changes automatically

We do change the output device if the specified output device is no longer available but the document states: cubeb never follow device changes automatically.

I am ok to reword these once setSinkId is done. Just want to make sure this issue is one someone's radar.

cubeb_devid, cubeb will only ever use the specified device and never
follow device changes automatically. In this case, the application may
Copy link
Member

Choose a reason for hiding this comment

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

audiounit-rust backend will automatically change the input device when the specified input_device is unplugged (cannot be used anymore). So this behavior need to be changed? Should we just return error instead when the specified input_device is gone?

manage device changes using @ref
cubeb_stream_register_device_changed_callback or @ref
cubeb_register_device_collection_changed.

@param context A pointer to the cubeb context.
@param stream An out parameter to be filled with the an opaque pointer to a
cubeb stream.
Expand Down