malgo

To use malgo in your Go project, install the package using go get. Note that malgo requires cgo to function. On Windows and macOS, no additional linking is required, while on Linux and BSD systems, it links against -ldl.

go get -u github.com/gen2brain/malgo

The DeviceCallbacks struct is used during InitDevice to define how the application responds to audio events.

• Data (DataProc): A function called for full-duplex I/O. It receives pOutputSample (for playback), pInputSamples (for capture), and the framecount.
  • If the device is playback-only, pInputSamples will be nil.
  • If the device is capture-only, pOutputSample will be nil.
  • The slices provided are byte slices ([]byte) representing the raw audio data.
• Stop (StopProc): A function called when the device has stopped.

type DataProc func(pOutputSample, pInputSamples []byte, framecount uint32)
type StopProc func()

type DeviceCallbacks struct {
	Data DataProc
	Stop StopProc
}

The ContextConfig struct allows you to customize the behavior of the audio context, including thread priority, memory allocation callbacks, and backend-specific settings.

Backend-Specific Configurations

• Alsa: AlsaContextConfig provides UseVerboseDeviceEnumeration.
• PulseAudio: PulseContextConfig allows setting PApplicationName, PServerName, and TryAutoSpawn (to autospawn the daemon).
• CoreAudio: CoreAudioConfig manages SessionCategory and SessionCategoryOptions.
• Jack: JackContextConfig allows setting PClientName and TryStartServer.

Global Settings

• ThreadPriority: Sets the priority for the audio threads.
• AllocationCallbacks: Allows providing custom OnMalloc, OnRealloc, and OnFree functions.
• LogCallback: A LogProc function to handle logging.

malgo supports a wide range of platforms and their respective audio backends:

• Windows: WASAPI, DirectSound, WinMM
• Linux: PulseAudio, ALSA, JACK
• FreeBSD/NetBSD/OpenBSD: OSS/audio(4)/sndio
• macOS/iOS: CoreAudio
• Android: OpenSL|ES, AAudio

You can intercept internal malgo logs by providing a LogProc function to SetLogProc. A LogProc is a function with the signature func(message string).

To stop logging, call SetLogProc(nil).

ctx.SetLogProc(func(message string) {
    fmt.Printf("malgo log: %s\n", message)
})

The Result type is an int32 that implements the Go error interface. It wraps miniaudio result codes. When an operation returns a Result that is not MA_SUCCESS, you can call its .Error() method to retrieve a descriptive error string prefixed with miniaudio: .

To check if an operation was successful, compare the returned Result against ErrGeneric (which represents MA_ERROR) or check if it matches the success state (though in practice, most users check if the result is non-zero or use the provided error constants).

// Example of how a Result might be used
res := someMalgoFunction()
if res != 0 { // Assuming 0 is success
    fmt.Println("Error occurred:", res.Error())
}

You can query a Context to find available audio hardware using Devices or DeviceInfo.

List all devices

Use Devices(kind DeviceType) to get a slice of DeviceInfo for either Capture or Playback devices.

Get specific device info

Use DeviceInfo(kind DeviceType, id DeviceID, mode ShareMode) to retrieve detailed information about a specific device identified by its DeviceID and requested ShareMode.

// List all playback devices
devices, err := ctx.Devices(malgo.Playback)
if err != nil {
    // handle error
}

for _, device := range devices {
    fmt.Printf("Device: %s\n", device.Name)
}

Use SampleSizeInBytes(format FormatType) to determine how many bytes a single sample occupies for a specific audio format. This is useful when manually managing audio buffers or calculating buffer sizes based on the FormatType being used.

// Example usage (assuming FormatType is defined elsewhere in the package)
bytes := malgo.SampleSizeInBytes(malgo.FormatS16)

Use DefaultDeviceConfig(deviceType DeviceType) to create a DeviceConfig populated with the library's default settings for a specific device type (e.g., playback or capture). This is the recommended starting point for configuring audio devices.

// Example: Initialize a default playback configuration
config := malgo.DefaultDeviceConfig(malgo.DeviceTypePlayback)