README
¶
coreaudio
Names the machine's audio devices, in pure Go with CGO_ENABLED=0, so a program
can send its sound somewhere in particular instead of wherever the system
happens to be pointing.
devs, err := coreaudio.Devices()
for _, d := range devs {
fmt.Println(d) // "VITURE" [1 out] 0ED43331-0000-0000-2021-010380100A78
}
out, err := coreaudio.DefaultOutput()
fmt.Println("sound is going to", out.Name)
The need is ordinary and the default is wrong often enough to matter. A film played on a pair of XR glasses draws its picture on the glasses and, with no device named, plays its sound out of the Mac's own speakers. Nothing reports an error, because nothing went wrong: the sound went to the default output, which is not where the person is looking.
Device.UID is the string AVFoundation and AudioQueue both take to be told
where to play, and it keeps identifying the device after a reboot or a re-plug,
unlike the numeric ids beside it, which do not.
Capture devices are listed too. Filtering them out here would leave a caller looking for a device by name unable to tell no such device from a device by that name that cannot play, and those call for different words.
Everything is bound through purego: no cgo, no Xcode, and the package cross-compiles.
Documentation
¶
Overview ¶
Package coreaudio names the machine's audio devices, so a program can send its sound somewhere in particular instead of wherever the system happens to be pointing.
The need is ordinary and the default is wrong often enough to matter: a film played on a pair of XR glasses draws its picture on the glasses and, with no device named, plays its sound out of the Mac's own speakers. Nothing reports an error, because nothing went wrong -- the sound simply went to the default output, which is not where the person is looking.
What is here is enumeration and identity, not playback. A device's Device.UID is the string AVFoundation and AudioQueue both take to be told where to play, and it is stable across reboots and re-plugs, unlike the numeric ids beside it, which are not.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrNoMute = errors.New("coreaudio: this device has no capture mute switch")
ErrNoMute says the device publishes no mute switch for capture.
⚠ IT IS COMMON, not exceptional. A mute switch is a property a device MAY have: many capture devices publish none and are silenced by setting their volume to zero instead, and some publish one per channel rather than a master one. So a caller that offers "mute the microphone" has to be ready to say it cannot, in words, rather than to fail.
var ErrNoVolume = errors.New("coreaudio: this device has no capture level")
ErrNoVolume says the device publishes no capture level.
var ErrUnsupported = errors.New("coreaudio: only macOS has CoreAudio")
ErrUnsupported is returned by every call off macOS. CoreAudio is a macOS framework; there is nothing here to fall back to, and pretending otherwise would hand a caller an empty device list that looks like a machine with no sound card.
Functions ¶
This section is empty.
Types ¶
type Device ¶
type Device struct {
// UID identifies the device to the rest of CoreAudio, and keeps identifying
// it after a reboot or a re-plug. It is what a setting should store; the
// name is what a person should read.
UID string
// Name is the name shown in Sound settings.
Name string
// Outputs is how many output streams the device publishes, and
// Inputs is how many input ones. A device is not necessarily either: a
// microphone has no outputs, and asking it to play sound would fail for a
// reason nobody would guess from "device not found".
Outputs, Inputs int
// contains filtered or unexported fields
}
Device is one audio device the system knows about.
func (Device) CanMute ¶ added in v0.2.0
CanMute reports whether the device has a capture mute switch to work.
⛔ ASK BEFORE OFFERING. A menu row or a key that silently does nothing is worse than one that is not there: it gets pressed again.
func (Device) CanSetVolume ¶ added in v0.2.0
CanSetVolume reports whether the device has a capture level to move.
⭐ IT IS THE OTHER WAY TO SILENCE A MICROPHONE, and on some devices the only one: measured on this machine, the MacBook's own microphone has a mute switch and the VITURE headset's has none. A caller that offers "mute the microphone" should ask for Device.CanMute first and fall back to setting this to zero.
func (Device) Muted ¶ added in v0.2.0
Muted reads the device's capture mute switch.
⛔ READ BEFORE WRITING, always. A key that means "mute" is pressed blind, and the only thing that knows whether the microphone is already off is the device -- a person may have used the switch on the hardware, or another application, since anything here last looked.
Source Files