Audio Zone Manager Library (AZM_Lib)

About

The Audio Zone Manager (AZM) is a suite of tools that processes Audio Data coming into your Cisco Codec and provides custom Commands, Statuses and Events for you to build Audio Automations through the devices Macro Editor

Minimum RoomOs Version	Webex Cloud	Webex Edge (Hybrid Cloud)	On-Premise	Microsoft Teams Room On Cisco Devices
11.16.1.1	✅ Yes	✅ Yes	✅ Yes	🟠 Unknown - Not Tested (Sep 9 2024)

Before you Start!
Key Terms
Release ChangeLog
Device Requirements
Installation
AZM Audio Configuration
AZM Library Reference
- Commands
- Statuses
- Events
Audio Design Considerations
TroubleShooting
Use Case Examples
Tutorial Videos
FAQ
- Is this Macro Supported?
- When does a Zone Change State?
- Can I have multiple Zone configurations?
- Can I run 2 different Audio solutions using AZM on the Same Codec?
- How is the Audio data evaluated?
- Can I edit this Macro?
- Are USB Microphones Supported?

Press on the Menu Icon to come back to the Table of Contents

Before you Start

The Library is provided "As-Is" for you to work with or branch from.
- NOTE: All Macros are considered Custom Code by Cisco and are not supported.
Please review this doc in full before jumping in. This is NOT a plug and play macro, it does require some setup as every space is unique.
If you have any questions, please refer the FAQ Section at the bottom.
Please review the Device Requirements below, before loading this into a project.

Key Terms

Term	Definition
AZM	Acronym for Audio Zone Manager
Library	Collection of functions to be imported into another project
Codec	Refers to the main body of a Cisco Video Conference device.
Cisco Ethernet Microphone	Refers to any Cisco branded Ethernet Microphones compatible with their video conferencing platform
AES67 Microphone	Refers to a microphone leveraging the AES67 Protocol for audio over IP
Zone	Configurable field of interest in a space. Zones leverage audio data on the codec, or external source, to specify states of High or Low activity
Assets	Customizable JSON objects. Assets are assigned to a zone to map the relationship between a zone and various pieces in your room design
External Data	Refers to data not generated by the Cisco Codec, but is provided through an external device or service
External[N]	Refers to the type of external data. [N] is a generic placeholder for both VuMeter and Gate related external data
Bucket	Refers to a collection of data generated by a single microphone input connector, whether it be USB, Analog, Ethernet or External[N]
Bins	A subset of data within a bucket storing hard values of information, such as VuMeter data, to be processed by the AZM library
Sample	The audio data captured at any one instance

Release ChangeLog

Click on any Release Below to learn more about them

v1.0.0 (Major Release)

Minimum RoomOS Updated from 11.11.1.9 to RoomOS 11.16.1.1
USB Input Connector Support
Voice Activity Detection
Sampling Modes
- Snapshot: Evaluates incoming audio data as a set, based on the sample size, then clears the samples for the next set (same as previous versions)
- Rolling: (New) Evaluates incoming audio data as it comes in once the sample size has been reached
External Data Input Connectors
- External Data allows another device to inject audio data into the AZM Library from an external source. This data could be from any source with access to the codec xAPI (Servers, Room Controllers, etc.)
- It leverages the Message Send API to send a custom payload to an existing solution leveraging the AZM library
- Support for External VuMeter data or External Gate Data
- Use cases include, but are not limited to:
  - Zone Capacity Expansion
  - Integrating 3rd party gear into existing macro solutions
  - Ingesting audio events from a node codec into a Primary
Bug Cleanup
Restructured Debugging Tools
Implementation of JSDoc Comments in code
Expanded Sample Microphone Configurations
New Sample Macro that leverages new Sample Microphone Configurations

v0.8.0 (Minor Release)

Added support for AZM_Lib Macro update Process.
- New Configs Introduced
  - config_AutomaticUpdates_Mode
    - Enables Automatic Updates Mode. This is a passive update tool. The macro will check for updates hosted on this repository, but will NOT install the new release for you. It's purely meant to notify you 😃
    - Notification can be found in the Macro Console and in the Control Panel UI
  - config_AutomaticUpdates_Schedule_Day
    - If config_AutomaticUpdates_Mode is not set to off, then this is the Day of the Week when the Macro will check for an update
  - config_AutomaticUpdates_Schedule_Time
    - If config_AutomaticUpdates_Mode is not set to off, then this is the Time of Day when the Macro will check for an update
Minimum RoomOS Updated from 11.8.X to RoomOS 11.11.1.9
- This version of AZM leverages the new Control Panel interface to spawn an AZM Notification Panel which was introduced in this version of RoomOS

v0.7.2 (Initial Release)

...

Device Requirements

Minimum RoomOS Software Version

RoomOS 11.16.1.1

Registration Compatibility

Minimum RoomOs Version	Webex Cloud	Webex Edge (Hybrid Cloud)	On-Premise	Microsoft Teams Room On Cisco Devices
11.16.1.1	✅ Yes	✅ Yes	✅ Yes	🟠 Unknown - Not Tested (Sep 9 2024)

Tested Codec Models

Product
Codec Pro
Codec EQ

Supported Microphone Types

NOTE: For all microphone types, directional microphones are preferred over omnidirectional. This helps refine the areas of interest for audio based automation.

Analog Microphones
Cisco Ethernet Microphones
AES67 Microphones
USB Microphones
External Data Sources

Installation

Get the Files

In the versions folder, find latest version of the Audio Zone Manager Library
- NOTE: It's recommended to use the Latest Version available
Select the AZM_Lib.js file and download it's raw file
- It is NOT recommended to alter the name of the file. The File should be labeled AZM_Lib.js
- Altering the Name would require altering the import syntax in your project

Install via the Web UserInterface

Log into the WebUI of the Codec
Navigate to Macro Editor
Either
- Drag and Drop the AZM_Lib.js file into the Macro UI
- Or select import from file... and select AZM_Lib.js wherever you save this on your computer
Save the AZM_Lib Macro
Do NOT activate AZM_Lib
- Activating the AZM_Lib macro does not harm your device, but it will consume a active macro slot on your device
- You have a limit of 10 active macros on any device, whereas the AZM_Lib is a developer library, it's best to import this library into you main project and activate that project instead

Install via Webex Control Hub

Log into Webex Control Hub with either Admin or Device Admin Privileges
Locate your Codec in the Devices interface
Select Actions in the top right hand corner
Select Macros
Import the AZM_Lib.js file
Keep the the AZM_Lib deactivated macro and Save
- Library Macros, or imports, do not need to be activate upon deployment

AZM Audio Configuration

Audio Zone Manager needs to be configured before use
Your configurations teach the Macro where your audio resources are listening in relation to the assets you assigned them
Though the configuration must be run at the start, you can recall the configuration setup command at any time in the script, should you have a solution that requires zones to be altered, such as a Combine and Divide space

Code View

const AZM_Audio_Configuration = {
  Settings: {                               // Description: The Settings node effects all audio processing by AZM
    Sample: {
      Size: 4,                              // DefaultValue: 4 || AcceptedValue: Integer || Description: Set the sample size for AZM Audio Collection
      Rate_In_Ms: 500,                      // DefaultValue: 500 || AcceptedValue: 10-1000 || Description: Set the sample rate for AZM Audio Collection
      Mode: 'Snapshot'                      // DefaultValue: Snapshot || AcceptedValue: <'Snapshot', 'Rolling'> || Description: Determine the profile in which Audio VuMeter data is evaluated
    },
    GlobalThreshold: {
      Mode: 'On',                           // DefaultValue: 'On' || AcceptedValue: <'On', 'Off'> || Description: On: Enable Global Audio Thresholds for All Audio Zones; Off: Enable Independent Audio Thresholds for All Audio Zones
      High: 30,                             // DefaultValue: 35   || AcceptedValue: 1-60          || Description: Set the High Global Threshold
      Low: 20                               // DefaultValue: 20   || AcceptedValue: 1-60          || Description: Set the High Global Threshold
    },
    VoiceActivityDetection: 'On'            // DefaultValue: 'On' || AcceptedValue: <'On', 'Off'> || Description: Use Voice Activity Detection to Re-Enforce High State transitions
  },
  Zones: [                                  // Description: The Zones object allows you to define one or more audio zones for the AZM Automation. This is an array
    {
      Label: 'Zone 1',                      // DefaultValue: 'Zone_N' || AcceptedValue: String || Description: Provide a label for your Audio Zone
      ControllerId: '0001',                 // DefaultValue: '0001' || AcceptedValue: String || Description: Used to identify the controller for External[N] Microphone Types
      Independent_Threshold: {
        High: 35,                           // DefaultValue: 35 || AcceptedValue: 1-60 || Description: Set the High Independent Threshold. Settings > Global > Threshold > Mode must be set to Off to access
        Low: 20                             // DefaultValue: 20 || AcceptedValue: 1-60 || Description: Set the Low Independent Threshold. Settings > Global > Threshold > Mode must be set to Off to access
      },
      MicrophoneAssignment: {
        Type: 'Microphone',                 // DefaultValue: 'Microphone' || AcceptedValue: <'Microphone' or 'Analog', 'Ethernet' or 'AES67', 'ExternalVuMeter', 'ExternalGate'> || Description: Define the Type of Microphone placed in this Zone
        Connectors: [                       // Description: Assign one of more connectors to your Zone. This is an Array
          {
            Serial: '',                     // DefaultValue: String || AcceptedValue: String || Description: For Cisco Ethernet Microphones Only, assign the microphone's Serial address of the Microphone associated to this Zone
            StreamName: '',                 // DefaultValue: String || AcceptedValue: String || Description: For AES67 Microphones, assign the microphone's StreamName associated to the Zone
            SubId: [1, 2, 3, 4],            // DefaultValue: Array  || AcceptedValue: [1-4]  || Description: SubIds to subscribe to
            Id: 1                           // DefaultValue: Integer || AcceptedValue: Integer || Description: For Analog, USB and External[N] Microphone Types, Assign the ConnectorId associated to the Zone. This ID corresponds to the physical input on the codec

          }
        ]
      },
      Assets: {                             // Description: Define any object associated to this Audio Zone. Asset Information will be provided when an Event Fires
        CustomAsset_1: 'My First Asset',    // NOTE: Any Objects nested within Assets are defined by You and have no based key or value pairing. This us an example of a custom asset
        CameraId: 1                         // A more real world example of an Asset
      }
    }
  ]
}

Click on any Path Below to learn more about its properties

AZM_Audio_Configuration.Settings.Sample.Size

Description: The Sample Size refers to how many VuMeter samples the AZM Library connects across all microphone connectors before determining the Audio Zone's state

Default Value: 4
Accepted Values: Any non-negative, non-zero, whole integer
DataType: Integer
Required: Yes
Value Definitions: N/A
Note: This value effects the performance and speed of the Audio Zone Status

AZM_Audio_Configuration.Settings.Sample.Rate

Description: The Sample Rate refers to how often a VuMeter sampled by the AZM is collected in milliseconds across all microphone connectors

Default Value: 500
Accepted Values: 10 to 1000
DataType: Integer
Required: Yes
Value Definitions: N/A
Note: This value affects the performance and speed of the Audio Zone Status

AZM_Audio_Configuration.Settings.Sample.Mode

Description: The Sample Mode refers to how sampled VuMeter data is as its collected

Default Value: Snapshot
Accepted Values: ['Snapshot', 'Rolling']
DataType: String
Required: Yes
Value Definitions:
- Snapshot: [N] number of VuMeter Samples are collected at a rate of [Y]ms (based on AZM_Audio_Configuration.Settings.Sample.Rate/Size). When [N] samples are collected, they are Averaged, and sent to determine their High or Low status. Once processed, all [N] sampled are purged for the next collection of samples and repeats the process
- Rolling: [N] number of VuMeter Samples are collected at a rate of [Y]ms (based on AZM_Audio_Configuration.Settings.Sample.Rate/Size). When [N] samples are collected, they are Averaged, and sent to determine their High or Low status. Once processed, the oldest sample is removed, and a new sample is taken in then the process repeats
Note: This value affects the performance and speed of the TrackZones Event

AZM_Audio_Configuration.Settings.GlobalThreshold.Mode

Description: Choose how you want audio thresholds handled in your space

Default Value: 'On'
Accepted Values: ['On', 'Off']
DataType: String
Required: Yes
Value Definitions: N/A

AZM_Audio_Configuration.Settings.GlobalThreshold.High

Description: The High threshold defined for all microphone connectors. Any Audio Zone that is greater than or equal too this value will transition to a _High_ state

Default Value: 25
Accepted Values: 1 to 60
DataType: Integer
Required: Yes
Value Definitions: N/A
Note: The High threshold should have a value greater than the Low threshold

AZM_Audio_Configuration.Settings.GlobalThreshold.Low

Description: The High threshold defined for all microphone connectors. Any Audio Zone that is lesser than or equal too this value will transition to a _Low_ state

Default Value: 15
Accepted Values: 1 to 60
DataType: Integer
Required: Yes
Value Definitions: N/A
Note: The Low threshold should have a value lesser than the High threshold

AZM_Audio_Configuration.Settings.VoiceActivityDetection

Description: This enables use of xStatus Audio Microphones VoiceActivityDetector Activity

Default Value: 'On'
Accepted Values: ['On', 'Off']
DataType: String
Required: Yes
Value Definitions: If set to "On", then the VoiceActivityDetector Status will be included in the Audio Evaluation process for High states. If the evaluated VuMeter Data meets the high Threshold set and a human voice is detected, then the state of the zone will report High
Note: Voice Detection is only handled on the Mix of the codec, meaning this won't isolate voice on a single audio input connector and produce an event. If ANY audio source has voice, VoiceActivity becomes true

AZM_Audio_Configuration.Zones[{Array}]

Note: The Zones nested values contain multiple blocks of similar properties. Below will cover all nested properties, but not all values belong to each connector type.

Warning: It's best practice **NOT** to mix Analog and Ethernet Microphones due to latency between the two microphone types. If possible, please choose only 1 microphone type for your room design and follow the format for that microphone type listed below.

AZM_Audio_Configuration.Zones[{Array}].Label

Description: A label you can assign to the zone. This is used to identify zones in your space.

Default Value: 'Zone_N'
Accepted Values: String
DataType: String
Required: No
Value Definitions: N/A

AZM_Audio_Configuration.Zones[{Array}].ControllerId

Description: Identifies the control processor responsible for effecting change against for this connector. It's used to validate the information is coming from the correct source.

Default Value: '0001'
Accepted Values: String
DataType: String
Required: Only required for External[N] microphone types
Value Definitions: N/A

AZM_Audio_Configuration.Zones[{Array}].Independent_Threshold.High

Description: The High threshold defined for the Zone it's defined within. Any Audio Zone that is greater than or equal too this value will transition to a _High_ state

Default Value: 35
Accepted Values: 1-60
DataType: Integer
Required: No
Value Definitions: N/A
Note: The High threshold should have a value greater than the Low threshold

AZM_Audio_Configuration.Zones[{Array}].Independent_Threshold.Low

Description: The Low threshold defined for the Zone it's defined within. Any Audio Zone that is greater than or equal too this value will transition to a _Low_ state

Default Value: 20
Accepted Values: 1-60
DataType: Integer
Required: No
Value Definitions: N/A
Note: The Low threshold should have a value lesser than the High threshold

AZM_Audio_Configuration.Zones[{Array}].MicrophoneAssignment.Connectors[{SubArray}].Serial

Description: For Cisco Ethernet Microphones Only, assign the microphone's Serial address of the Microphone associated with this Zone. This tells the Macro how to find the Connector ID and map the correct audio information to your Zone

Default Value: ''
Accepted Values: String
DataType: String
Required: Only if using Cisco Ethernet Microphones
Value Definitions: N/A

AZM_Audio_Configuration.Zones[{Array}].MicrophoneAssignment.Connectors[{SubArray}].StreamName

Description: For AES67 Microphones Only, assign the microphone's StreamName of the Microphone associated with this Zone. This tells the Macro how to find the Connector ID and map the correct audio information to your Zone

Default Value: ''
Accepted Values: String
DataType: String
Required: Only if using AES67 Ethernet Microphones
Value Definitions: N/A

AZM_Audio_Configuration.Zones[{Array}].MicrophoneAssignment.Connectors[{SubArray}].SubId

Description: For Ethernet-based Microphones, these are the SubIds (or media channels) to subscribe to. 3rd party microphones may vary in the number of streams

Default Value: []
Accepted Values: [1-8] (Microphone Dependent)
DataType: Integer Array
Required: Only if using Ethernet-based Microphones
Value Definitions: N/A
Note: Not all microphones have multiple SubIds. Many may mix the stream and output 1 channel

AZM_Audio_Configuration.Zones[{Array}].MicrophoneAssignment.Connectors[{SubArray}].Id

Description: For Analog Microphones, assign the ConnectorId associated with the Zone. This is the physical connector id found on the codec body

Default Value: 1
Accepted Values: 1-N
DataType: Integer
Required: Only if using Analog Microphones
Value Definitions: N/A
Note: Recommended to use Directional Analog Microphones

AZM_Audio_Configuration.Zones[{Array}].Assets

Description: Assign unique objects under Assets to be assigned to this zone. This could contain any nested object for your design

Default Value: {}
Accepted Values: JSON Object Literal
DataType: JSON Object Literal
Required: No
Value Definitions: N/A
Note: Assets may change from project to project

AZM Library Reference

Commands

AZM.Command.Zone.Setup(AudioConfiguration)

Description: Initializes all Zones and Audio Input Connectors within the scope of your Project. Review the AZM AudioConfiguration Section of this Guide to learn how to configure

Architecture: Asynchronous
Required: Yes

NOTE: This function should run before accessing all other objects within AZM

Parameters: AudioConfiguration

Click for Sample Code

import xapi from 'xapi';

// Import the Audio Zone Manager Library
import { AZM } from './AZM_Lib';

// Create your Audio Configuration Object
const AudioConfiguration = {/* Populate this Object */};

// Define your Script initialization function
async function init(){
  await AZM.Command.Zone.Setup(AudioConfiguration);
  
  // Your Code
};

// More Code

AZM.Command.Zone.Monitor.Start()

Description: Starts VuMeter sampling on Audio Input connectors defined in AudioConfiguration object.

Architecture: Asynchronous
Required: No

NOTE: Enabling the VuMeter will turn ON the LED light on Cisco Microphones, even if off a call

Parameters: N/A

Click for Sample Code

xapi.Event.CallSuccessfull.on(async event => {
  await AZM.Command.Zone.Monitor.Start();
});

AZM.Command.Zone.Monitor.Stop()

Description: Stops VuMonitoring on configured Audio Inputs

Architecture: Asynchronous
Required: No

NOTE: Disabling the VuMeter will turn OFF the LED light on Cisco Microphones, unless you're connected to a call

Parameters: N/A

Click for Sample Code

xapi.Event.CallDisconnect.on(async event => {
  await AZM.Command.Zone.Monitor.Stop();
});

AZM.Command.Zone.List()

Description: Returns an array of all current Zone information. Especially useful for discovering ZoneIds

Architecture: Synchronous
Required: No
Parameters: N/A

Click for Sample Code

console.log(AZM.Command.Zone.List())
// Outputs array of all current zone information

Statuses

AZM.Status.Audio.Zone[ZoneId].get()

Description: Get information about your zone by ZoneId when

Architecture: Synchronous
Required: No

NOTE: ZoneId's are appended to your AudioConfiguration object when AZM.Command.Zone.Setup(AudioConfiguration) has run. ZoneId's are sequential, based on the index of your Audio Zones, starting at 1

Parameters: N/A

Click for Sample Code and Result

console.log(AZM.Status.Audio.Zone[1].get());

/*
Result
{ 
  Id: Integer,                        // The ZoneId you requested
  Label: String,                      // The ZoneLabel you Provided
  Connectors: Array,                  // An array of ConnectorIds
  State: <'Unset', 'High' or 'Low'>   // The State of a Zone
}
*/

AZM.Status.Audio.Zone[ZoneId].State.get()

Description: Get the State of your zone by ZoneId when

Architecture: Synchronous
Required: No

NOTE: ZoneId's are appended to your AudioConfiguration object when AZM.Command.Zone.Setup(AudioConfiguration) has run. ZoneId's are sequential, based on the index of your Audio Zones, starting at 1

Parameters: N/A

Click for Sample Code and Result

console.log(AZM.Status.Audio.Zone[1].State.get());

/*
Result
'Unset', 'High' or 'Low'              // The State of a Zone
*/

Events

AZM.Event.TrackZones.on(event => ...)

Description: Subscribe to changes to all Zone events defined within your scope.

NOTE: As events come in, AZM.Event.TrackZones.on will update the state in AZM.Status.Audio.Zone[ZoneId].State.get() and AZM.Status.Audio.Zone[ZoneId].get()
Required: Yes
Parameters: event

Click for Click for Sample Code and Event Callback Details

AZM.Event.TrackZones.on(event => {
  console.log(event)
  // As the events Change a message will show on the OSD indicating the Zone State
  xapi.Command.UserInterface.Message.Alert.Display({
    Title: event.Zone.Label,
    Text: `ZoneId: [${event.Zone.Id}] state set to [${event.Zone.State}]<p>Asset: ${event.Assets.toString()}`
  })
})

/*
Event Callback

{
  Zone: {                                   // Information about the Zone that caused the Callback to fire
    Label: String,                          // The name of the Zone provided in the AudioConfiguration
    State: <'Unset', 'High' or 'Low'>,      // The current State of the Zone
    Id: Integer                             // The ZoneId of the newest Zone Callback
  },
  Connector: {                              // Information about the Connector/SubId that caused the Callback to fire
    Type: <'Ethernet', 'AES67', 'Microphone', 'Analog' or 'USB'>, // The Type of Microphone Connector
    State: <'Unset', 'High' or 'Low'>,      // The current state of this Connector 
    Id: Integer,                            // The ID of the connector
    SubId: Integer                          // The SubId responsible for the Callback to fire
  },
  Assets: {},                               // Developer Defined Assets to Track
  DataSet: {                                // The original data processed in the event
    VuMeter: {                              // Data associated to the VuMeter
      Average: Integer,                     // The average value of the DataSet
      Peak: Integer,                        // The Peak Value of the DataSet
      Sample: Array                         // The raw set of data evaluated
    }
  }
}

*/

Audio Design Considerations

Refining an Audio Zone in your space requires good control of your physical audio resources
It's recommended to use Directional Microphones or a Microphone Array with clearly Defined Zones
Audio Zones with poorly defined audio separation in their pickup fields will produce false positives in your Audio Zone Automation

Below is an example image of Good Audio placement using the Cisco Table Microphone Pro (Image not to scale)

Both Zones A and B have ample separation, thus producing reliable Audio Zone Automation

Here is an example image of Poor Audio Placement (Image not to scale)

Zone's A and B overlap at the center, so any information captured here could lean to either zone, resulting in poor Audio Zone Automation

Here is an example image of Poor Placement, but with a better Audio Configuration applied to the AZM Configuration (Image not to scale)

By only including SubIds 3 and 4 for both Microphones defined in Zone A and to only include SubIds 1 and 2 for both Microphones defined in Zone B you can still achieve good separation for reliable automation thus correcting this issue
NOTE: Though the AZM Library is ignoring these SubIds for automation, the speech audio from all 4 microphones will still be mixed and sent into the call (unless configured otherwise)

TroubleShooting

AZM's base script has a few select logs to print to the console which has relative meaning for a live deployment
However, there are additional logs you can enable in the AZM library itself you can use to troubleshoot a specific process, should you need too
These logs need to be turned on in the AZM_Lib macro, starting on line 79
NOTE: It's best to leave these additional debug logs as false as they can produce ALOT of information and could slow a browser session if left true for too long

/**
 * AZM Debug flags should remain `false` by default as they produce ALOT of information and could slow a browser session if left `true` for too long
 * 
 * Only set `true` only when you need to troubleshoot
 * 
 * When complete, please set all flags to `false` to improve browser performance
 * 
 * @see createDebugMethod
 * @see console.AZM
 */
const AZM_DebugFlags = {
  SetupDebug: false,                      // Enables Debugging for the AZM Setup Process
  ZonesDebug: false,                      // Enables Debugging for changes in Zones
  MonitorDebug: false,                    // Enables Debugging for Starting and Stopping the AZM Monitor
  Analog_BucketDebug: false,              // Enables Debugging for processing Analog Audio data
  Ethernet_BucketDebug: false,            // Enables Debugging for processing Ethernet/AES67 Audio data
  USB_BucketDebug: false,                 // Enables Debugging for processing USB Audio data
  ExternalVuMeter_BucketDebug: false,     // Enables Debugging for processing ExternalVuMeter Audio Data
  ExternalGate_BucketDebug: false,        // Enables Debugging for processing ExternalGate Audio Data
  MessageSendEvent_Debug: false,          // Enables Debugging for raw event data coming into the Message Send Event
  AudioInputConnectorEvent_Debug: false   // Enables Debugging for raw event data coming into the Audio Input Connector Event
};

Setting any of the above values to true will enable more logs to print to the Macro Console

To view these logs, you must also enable the Debug log level under the Severity drop down in the Macro Console

Use Case Examples

Camera Automation

Leveraging the Zone States emitted by this script, you can:
- Switch between different connectors as folks speak in different Audio Zones you define
- Enable an extended Zoom Range for the base speakertracking solution provided by the codec

Audio Ducking

Leveraging the Zone States emitted by this script, you can dynamically raise or lower Microphone input Gain in a space

Screen Layout Automation

Leveraging the Zone States emitted by this script, you can alter the layouts of your screens as a speaker transitions between specific Audio Zones

Tutorial Videos

Analog Microphone Configuration Guide
- Learn how to configure the AZM Library for use with Analog Microphones
Cisco Ethernet Microphone Configuration Guide
- Learn how to configure the AZM Library for use with Cisco Ethernet Microphones
AES67 Microphone Configuration Guide
- Learn how to configure the AZM Library for use with AES67 Microphones
AZM Macro Tutorial
- Learn how to make use of the AZM Functions to start building your own Macros
Version 1.0.0 Update (Coming Soon)
- A full review of the AZM version 1.0.0 update
ExternalVuMeter Microphone Configuration Guide(Coming Soon)
- Learn how to configure the AZM Library for use with an external processor's VuMeter Data
ExternalGate Microphone Configuration Guide(Coming Soon)
- Learn how to configure the AZM Library for use with an external processor's Gate Data
External[N] Microphone Room Design Guidance(Coming Soon)
- Learn why External[N] Microphones were introduced into AZM and how to make use of them in your solutions
External[N] Postman Collection Testing Guide(Coming Soon)
- Learn how to install and use the External[N] Postman Collection
AZM in the Campfire Blueprint Macro
- A review on how the Campfire Blueprint Macros utilize the AZM Library
- Campfire Blueprint Macros

FAQ

Is this Macro Supported by Cisco TAC?

No, all Macros are considered Custom Code by Cisco and are not supported.

When does a Zone Change State?

There are several rules in place to set the State of a Zone
States
- High: When at least 1 Audio ConnectorId, or SubId in the case of Ethernet Microphones, defined within a Zone moves to a High State.
- Low: When all Audio ConnectorIds, or SubIds, defined within a Zone move to a Low State
- Unset: This only occurs on setup, when no audio data has been fed into the script. If at least 1 Audio ConnectorId, or SubIds, are Low or High, the Zone is no longer Unset

Can I have multiple Zone configurations?

Yes, I recommend you at least enable one at the start of the script, but you could have multiple Zone Configuration objects and can load a new object by recalling the AZM.Command.Zone.Setup(AZM_Audio_Configuration) function again in your script

Can I run 2 different Audio solutions using AZM on the Same Codec?

It's not recommended. AZM was not built for that application and when working with multiple audio solutions on a single codec, then it's best to keep the one solution defined under the same macro
Though, you can define as many zones as you'd like, so you could in fact define a new zone with different assets and settings, but leverage the same microphone connectors should you need to

How is the Audio data evaluated?

The TrackZones Event Subscribes to the Audio VuMeter of your defined microphones
This data is packaged into "bins" that are instantiated in an [X]_Bucket Class during the Zone Setup process
These bins will fill up at a pace that's defined by both your Sample Size and Sample Rate value in the AudioConfiguration Object
Once a bin matches the Sample Size value, the data collected is then Averaged and Compared against the High and Low thresholds set in the AudioConfiguration Object, then the bin is cleared for the next batch of data
If the Average is equal to or above the High threshold, the connector associated to the incoming data is set to a High State
- Else if the Average is equal to or above the Low threshold, the connector associated to the incoming data is set to a Low State
The new Connector State is then passed up into the Zone Status, and further compared to the additional connector states within the Zone to determine the Zone State

Can I edit this Macro?

Of Course, it's an Open Script, feel free to fork and edit to your liking

Can I define multiple zones off the same Cisco Ethernet or 3rd Party AES67 Microphones

Yes, but do so with caution
A fix to allow this came with the release of the AZM_Lib version 1.0.0, but the data processed in the AZM Library is quite simple and may not result in adequate triggers for those zones
- In a test with a single Cisco Table Mic Pro, I've split the microphone into 2 unique zones. The left zone using SubIds 3 and 4 and the right zone using SubIds 1 and 2
- Sitting about 1 meter (3 feet) away from the left side of the microphone, there was only a 7% increase, on average, of high responses on the left side of the microphone compared to the right
- This highlights little change between the 2 zones on a single Cisco Mic Pro
- Now, with that said, it's not blocked, so if you find a successful work-around consider submitting a an Example Audio Configuration to this repository! Collaboration Technology needs collaborators!

Why am I getting errors installing the AZM Library through Webex Control Hub?

It's difficult to know without the exact error on hand, but below is an alternative method for Macro Installation via Webex Control Hub you could try
- Log into Webex Control Hub with either Admin or Device Admin Privileges
- Locate your Codec in the Devices interface
- Select All Configurations
- Look for and Set xConfiguration Macros EvaluateTranspiled to False on your endpoint
- Close the All Configurations Menu
- Select Actions > Run xCommand
- Look for and Select Macros Macro Save
  - Set Overwrite to True
  - Set Transpile to False
  - Name the macro AMZ_Lib
  - Set the full AZM_Lib script in the body
  - Select Run

Are USB Microphones Supported?

Yes, support for USB Microphones came with the release of the AZM_Lib version 1.0.0
Note: Cisco Codec's only support 1 USB Audio Microphone Input, which limits you to one Audio Zone. You could either create zones with other microphone types, or leverage the new External[N] microphone types

Name		Name	Last commit message	Last commit date
Latest commit History 26 Commits
images		images
legacy_readme_files/v0.8.0 and older		legacy_readme_files/v0.8.0 and older
.DS_Store		.DS_Store
AZM_Lib.js		AZM_Lib.js
AZM_Sample_Macro.js		AZM_Sample_Macro.js
AZM_Sample_Mic_Configurations.js		AZM_Sample_Mic_Configurations.js
LICENSE		LICENSE
README.md		README.md
manifest.json		manifest.json

License

ctg-tme/audio-zone-manager-library-macro

Folders and files

Latest commit

History

Repository files navigation

Audio Zone Manager Library (AZM_Lib)

About

Table of Contents

Before you Start

Key Terms

Release ChangeLog

Device Requirements

Minimum RoomOS Software Version

Registration Compatibility

Tested Codec Models

Supported Microphone Types

Installation

Get the Files

Install via the Web UserInterface

Install via Webex Control Hub

AZM Audio Configuration

Code View

AZM Library Reference

Commands

Statuses

Events

Audio Design Considerations

TroubleShooting

Use Case Examples

Camera Automation

Audio Ducking

Screen Layout Automation

Tutorial Videos

FAQ

Is this Macro Supported by Cisco TAC?

When does a Zone Change State?

Can I have multiple Zone configurations?

Can I run 2 different Audio solutions using AZM on the Same Codec?

How is the Audio data evaluated?

Can I edit this Macro?

Can I define multiple zones off the same Cisco Ethernet or 3rd Party AES67 Microphones

Why am I getting errors installing the AZM Library through Webex Control Hub?

Are USB Microphones Supported?

About

Topics

Resources

License

Stars

Watchers

Forks

Releases 3

Packages 0

Languages

Packages