Multi-Room Music (MRM) Library Classes

Multi-Room Music (MRM) enables synchronous playback of audio across multiple Alexa Built-in devices. This document introduces the MRM client library (also known as Whole Home Audio) and the delegate classes that are used to interface with the library.

Introduction

The MRM library is an implementation of the MRM feature that:

  • Manages communication with Alexa
  • Synchronizes time between group members on the network
  • Retrieves and decodes audio content from music service providers
  • Manages the propagation of audio content between primary and secondary devices in the group
  • Passes timestamped audio sample buffers to group members

The primary device is responsible for maintaining a connection with Alexa and propagating content across the local network to members of the group. It also determines when synchronized content should be rendered across group members. The secondary device is responsible for connecting to the primary device. The primary device is defined by Alexa, and primary/secondaryAlexa interactions are handled by the MRM library.

This diagram illustrates MRM integration into the AVS software stack:

The MRM client library in context

Delegate Classes and the MRM SDK

The AVS client accesses the MRM client library using the WHA class. Six delegate classes must be implemented before using the WHA class:

  • CloudDelegate - Enables the exchange of directives and events between the MRM library and an AVS client.
  • FocusDelegate - Exchanges application focus and playback state information between the MRM library and the AVS client.
  • DeviceInfoDelegate - Provides device information, such as IP address.
  • TimeDelegate - Surfaces the high-resolution timer functionality from the device or operating system. This class also holds the relative delay constants measured during unit testing.
  • PlaybackDelegate - Receives timestamped audio output from the MRM client library. It is in the critical path of getting the current delay of the audio pipeline through the mixer and the audio driver and then using that delay plus the MRM synchronized time to send samples to the mixer down to the hardware at the right time such that they play in sync.
  • LoggingDelegate - Captures logging messages produced by the MRM library for debugging.

Unit Testing with the Cluster Kit

Device makers can request a custom build of the MRM client library that functions without an AVS client. Rather than expecting directives from Alexa, it connects to a device at specific network location. his custom build requires two customized Amazon Echo Dots. When compiled into a provided sample app and configured on the network according to instructions, a device running this build of the MRM client library will participate in an MRM group with the provided Dots.

This configuration is useful for unit testing to test implementations of an audio pipeline. It also allows for early measurement of relative skew and drift between the device and the Echo Dots prior to implementation of the AVS client. The output of this skew testing should be included in the implementation of the TimeDelegate to set the default play offset.

AVS Device SDK Integration

Upon request, Amazon will provide a version of the AVS Device SDK that is enabled to interact with the MRM client library. These versions implement the interface between the AVS Device SDK and the CloudDelegate and FocusDelegate classes.

Device makers that use the AVS Device SDK are only required to implement the operating system and device-specific delegate classes:

  • DeviceInfoDelegate
  • TimeDelegate
  • PlaybackDelegate
  • LoggingDelegate
Was this page helpful?

Last updated: Nov 27, 2023