---
title: roAudioPlayerMx
slug: develop/roaudioplayermx
docTags: 
createdAt: 2025-03-11T07:07:18.732Z
---

This object allows you to mix audio files, as well as HLS audio streams. Each roAudioPlayerMx object contains two internal audio players: The main audio playlist consists of queued audio tracks that play sequentially, while the audio overlay plays files on top of the main playlist. A fade will not occur if it is called while an overlay is playing, but the next audio track will start playing as expected. 

Tracks are queued to `PlayFile()` with their fade parameters specified in an [associative array](docId\:sb0Om1Y-OQlapFqNFS0XY). These are the parameters you can pass to `PlayFile()`:

- `Filename`: The filename of the track
- `FrontPorch`: The length (in milliseconds) to skip from the start of the track. This value is 0 by default.
- `FadeOutLocation`: The location (in milliseconds) of the fade out relative to the value of the `FrontPorch`. If the `FrontPorch` value is `0` (which is the default setting), and the `FadeOutLength` value is non-zero, then the fade out is calculated back from the end of the file.
- `FadeOutLength`: The length of the fade out (in milliseconds). This value is 0 by default.
- `SegueLocation`: The location (in milliseconds) of the event that triggers the next audio file to play. This location is relative to the first audio file that is played. If the `SegueLocation` parameter is not included, the value defaults to the `FadeOutLocation`.
- `BackPorchLocation`: The location (in milliseconds) of the termination point for the audio track. This location is relative to the first audio file that is played. If the `BackPorchLocation` parameter is not included, the audio file plays to the end. The value is 0 by default, which disables the back porch.
- `TrackVolume`: The relative volume of of the audio track, measured as a percentage. Specify the percentage using values between 0 and 100.
- `EventID`: The ID for an audio event.
- `EventTimeStamp`: The timestamp for the audio event. There can only be one event per audio file.
- `QueueNext`: The queuing of an audio track. Set the parameter value to 1 to queue an audio file to play after the current track.
- `Overlay`: The overlay specification of an audio track. Set the parameter value to 1 to fade down the main audio playlist while playing the audio track as an overaly. Overlays have additional parameters:
  - `AudioBedLevel`: The volume-level percentage of the main audio playlist while the overlay is playing. Specify the percentage using values between 0 and 100.
  - `AudioBedFadeOutLength`: The fade-out length of the main audio playlist.
  - `AudioBedFadeInLength`: The fade-in lenth for the length of the underlying audio track once the segue is triggered.
- `FadeCurrentPlayNext`: A fade command. Set the parameter value to 1 to fade out the current main audio playlist track and fade in the designated audio file.
- `CrossfadeCurrentPlayNext`: A crossfade command. Set the parameter value to 1 to force an immediate crossfade between the current main audio playlist track and the designated audio file.
- `UserString`: A string that can be set to a unique value for each *roAudioPlayerMx* instance. This string is returned with every event generated by the instance. Since all current platforms can support multiple *roAudioPlayerMx* instances running at the same time, the UserString allows the script to distinguish between event returns.

The following diagram illustrates how some of these timing parameters work together:

::Image[]{src="https://api.archbee.com/api/optimize/511c8QBH-VHiwWnyzIwUb/gl6WpSStMN95R89anRs4K_ormroaudioplayermx.png" size="60" width="864" height="274" position="center" darkWidth="864" darkHeight="274" showCaption="false"}

The following script illustrates a simple crossfade between audio tracks:

```text
a = CreateObject("roAudioPlayerMx")
 
track1 = CreateObject("roAssociativeArray")
track1["Filename"] = "file1.mp3"
track1["FadeInLength"] = 4000
track1["FadeOutLength"] = 4000
track1["QueueNext"] = 1
 
track2 = CreateObject("roAssociativeArray")
track2["Filename"] = "file2.mp3"
track2["FadeInLength"] = 4000
track2["FadeOutLength"] = 4000
track2["QueueNext"] = 1
 
a.PlayFile(track1)
a.PlayFile(track2)
```

## ifMediaTransport

See *roVideoPlayer* for a description of *ifMediaTransport* methods.

## ifAudioControl

See *roAudioPlayer* for a description of *ifAudioControl* methods.

## ifSetMessagePort

### SetPort(a As Object)

## ifUserData

### SetUserData(user\_data As Object)

Sets the user data that will be returned when events are raised.

### GetUserData() As Object

Returns the user data that has previously been set via `SetUserData()`. It will return Invalid if no data has been set.

## ifIdentity

### GetIdentity() As Integer

:::hint{type="info"}
The *ifIdentity* interface has been deprecated. We recommend using the *ifUserData* interface instead.
:::

## ifAudioControlMx

### SetDecoderCount(a As Integer) As Boolean