This example program outputs a short beep. To keep it simple, a few details (primarily error-checking) are skipped. This program only includes the operations required to produce the beep. The steps are as follows:
|Note: Consult the online example code for more advanced programs.|
Provides the core ML library functionality
Provides simple utility functions built on the core library
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:
Query the local system to find the first physical device that matches your desired device name.
Look in that device to find its first output jack.
Find an output path that goes through that jack.
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, &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 );
|Note: Sometimes an mlOpen call can fail due to insufficient resources (typically because too many applications may already be using the same physical device).|
A single (mono) audio channel
A gain of -12dB
A sample rate of 44.1kHz
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.
mlpv controls; MLreal64 gain = -12; /* decibels */ controls.param = ML_AUDIO_FORMAT_INT32; controls.value.int32 = ML_AUDIO_FORMAT_S16; controls.param = ML_AUDIO_CHANNELS_INT32; controls.value.int32 = 1; controls.param = ML_AUDIO_GAINS_REAL64_ARRAY; controls.value.pReal64 = &gain controls.length = 1; controls.param = ML_AUDIO_SAMPLE_RATE_REAL64; controls.value.real64 = 44100.0; controls.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).
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.
Construct an MLpv message that describes the buffer. That message must include both a pointer to the buffer and the length of the buffer (in bytes):
MLpv msg; msg.param = ML_AUDIO_BUFFER_POINTER; msg.value.pByte = ourAudioBuffer; msg.length = sizeof(ourAudioBuffer); msg.param = ML_END;
Send the buffers message to the opened path:
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.|
The program can sleep while the device is busy working on the message as follows:
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");