To begin, you will need the following files:

You may choose to use only the core library or you may find it convenient to use the simpler utility functions.

Include the files as follows:

#include <ML/ml.h>
#include <ML/mlu.h>

You must query the capabilities of the system to find a suitable digital media device with which to perform your audio output task. To do that, you must search the ML capability tree, which contains information on every ML device on the system.

In your search, you should start at the top of the tree as follows:

In this case, assuming that the device name is being passed in as a command-line argument, you can use some of the utility functions to find a suitable output path:

MLint64 devId=0;
MLint64 jackId=0;
MLint64 pathId=0;

mluFindDeviceByName( ML_SYSTEM_LOCALHOST, argv[1], &devId );
mluFindFirstOutputJack( devId, &jackId );
mluFindPathToJack( jackId, &pathid, memoryAlignment );

An open device output path provides your application with a dedicated connection to the hardware. It also allocates system resources for use in subsequent operations. The device path is opened with an mlOpen call as follows:

mlOpen( pathId, NULL, &openPath );

If the mlOpen call is successful, you will get an open path identifier. All operations using that path must use its identifier.

---

Note: Sometimes an mlOpen call can fail due to insufficient resources (typically because too many applications may already be using the same physical device).

---

Set up the path you just opened for your operation. In this case, you will use signed 16-bit audio samples with the following:

In ML, applications communicate with devices using messages. These messages are known as MLpv messages, because they consist of a list of param/value pairs. An MLpv ends with an ML_END to indicate completion.

For example:

mlpv controls[5];
MLreal64 gain = -12; /* decibels */

controls[0].param = ML_AUDIO_FORMAT_INT32;
controls[0].value.int32 = ML_AUDIO_FORMAT_S16;
controls[1].param = ML_AUDIO_CHANNELS_INT32;
controls[1].value.int32 = 1;
controls[2].param = ML_AUDIO_GAINS_REAL64_ARRAY;
controls[2].value.pReal64 = &gain
controls[2].length = 1;
controls[3].param = ML_AUDIO_SAMPLE_RATE_REAL64;
controls[3].value.real64 = 44100.0;
controls[4].param = ML_END;

Notice that this message contains both scalar parameters (for example, the number of audio channels) and an array parameter (the array of audio gains).

After you have constructed the MLpv controls message, you must set the controls on the open audio path as follows:

mlSetControls(openPath, controls);

This call makes all the desired control settings and does not return until those settings have been sent to the hardware. If it returns successfully, it indicates that all of the control changes have been committed to the device (and you are free to delete or alter the controls message).

---

Note: All control changes within a single controls message are processed atomically: either the call succeeds (and they are all applied) or the call fails (and none are applied).

---

Assuming that the call succeeded, the path is now set up and ready to receive audio data.

This example assumes that you have already allocated a buffer in memory and filled it with audio samples. To send that buffer to the device for processing, do the following:

When the message is sent, it is placed on a queue of messages going to the device. The mlSendBuffers call does very little work: it gives the message a cursory look before sending it to the device for later processing.

---

Note: Unlike the mlSetControls call, the mlSendBuffers call does not wait for the device to process the message, it simply enqueues it and then returns.

---

You must tell the device to start processing enqueued messages. This is done with the mlBeginTransfer call as follows:

mlBeginTransfer(openPath);

The program can sleep while the device is busy working on the message as follows:

sleep(5)

Using sleep is simple, but the example in Chapter 4, “Realistic Audio Output Program” shows a better approach. See “Step 6: Begin the Transfer” in Chapter 4.

As the device processes each message, it generates a reply message that is sent back to our application. By examining that reply, you can confirm that the buffer was transferred successfully, as follows:

MLint32 messageType;
MLpv* message;

mlReceiveMessage(openPath, &messageType, &Message );

if( messageType == ML_BUFFERS_COMPLETE )
  printf("Buffer transferred!\n");

Once you have verified that the buffer transferred successfully, you can close the path as follows:

mlClose(openPath);

Closing the path ends active transfer and frees any resources allocated when the path was opened.