Reggae tutorial: Saving audio in user selected format

Grzegorz Kraszewski

Introduction

Except of automatic media decoding, Reggae has also a feature on automatic encoding. There is one fundamental difference between these two however. In case of decoding, a format of decoded media, codec parameters, stream parameters, metadata, all this comes from the decoded datastream. When media are encoded, format, codec parameters and metadata have to be set by application.

Usually an application wants to offer all available formats to user. It means that application author has to maintain GUI for all codecs and their parameters. Also such a GUI would have to be updated with every new released codec. Reggae changes this and makes application programmer's life easier. The main rule is that multiplexer and encoder classes provide GUI. Reggae gathers those GUIs in a single object and returns it to application. Then application can embed this compound GUI object into its own interface. User can use this object to select encoder and its parameters. This is not all however.

After user selects output format and its parameters, Reggae can create encoder-muxer pair, read parameters and metadata from the GUI, and set them to proper objects. Then application connects the data source at input and output stream class at output. After triggering processing with MMM_Play() method on the output stream object, audio data is written.

Using Reggae media save API, application programmer need not to care about what formats Reggae supports. To say more, even if new codecs are released after the application release, the application will use them without a need for update.

Preparing Source Data

Source audio data may be prepared either as a static buffer, or generated on-demand. Static buffer technique is simplier and will be described here. Realtime generation may be accomplished by writing a custom Reggae class (see source code of U1Synth), or by using datapush.stream class. Source data also may come from Reggae, for example from some decoded audio file. This is the case for an audio converter Zormanita, which also is opensourced.

Data in a buffer should be in one of Reggae common formats. There are three common formats for audio: INT16, INT32 and FLOAT32. The choice depends on purpose and required processing quality. INT16 is the fastest format and is best suited for playback. FLOAT32 has more or less 24-bit resolution and may be handy for many synthesis algorithms, which are often easier to implement with floating point math. INT32 is the slowest one, but provides the best quality, usually better than further stages of processing. All three formats use signed numbers with host native byte order (which is big endian for PowerPC). Also floating point range is [−1.0; +1.0]. While it may be temporarilly exceeded, any Reggae class is allowed to clip data to this range. If audio is multichannel, channels are interleaved (for stereo the order is L, R).

Start address of the buffer should be AltiVec aligned. While this is not a requirement for data fetched via memory.stream object (more about it later), it may speed the processing up a bit. The easiest way to get the alignment it is to alloc the buffer with MediaAllocVec() function of multimedia.class. On the other hand buffer size need not to be aligned other than to the size of a single audio frame (set of samples of all the channels for one time point). Of course filling the buffer with data is up to application. In the example code below a buffer is created with 1 second of monophonic audio sampled at 44.1 kHz. It contains 44 100 INT16 audio samples, so the size of buffer is 88 200 bytes.

WORD *Buffer;

Buffer = (WORD*)MediaAllocVec(88200);

Then the buffer is filled with sound. As an example it is shown how it can be filled by a 1 kHz sine wave.

LONG i;

for (i = 0; i < 44100; i++) Buffer[i] = (WORD)(sin(2000 * M_PI * i / 44100) * 32767.0);

The code is totally unoptimized, but has been left as such to be easy readable.

Creating Format Selection GUI

Creating a MUI object containing format selector and GUIs for all encoders is very easy. It is just one call to MediaGetGuiTagList() function. As the name suggests, a taglist can be used to control the GUI creation. Here is an example of it:

Object *FormatSelector;

FormatSelector = MediaGetGuiTags(
  MGG_Type, MGG_Type_Muxers,
  MGG_Media, MMT_SOUND,
  MGG_Selector, MGG_Selector_List,
  MUIA_Frame, MUIV_Frame_Group,
  MUIA_Background, MUII_GroupBack,
TAG_END);

Let's discuss the tags. The first one, MMG_Type selects type of Reggae classes queried for GUI. There are two possibilities currently. MGG_Type_Muxers is used when one encodes and saves media stream. There is also MGG_Type_Filters, which may be used for create Reggae filter selector for media processing. The second one will be covered in other articles. The next tag, MGG_Media defines kind of saved media. When one has audio data it makes no sense to display image or video formats. The value MMT_SOUND makes sure only audio codecs are shown. The third tag, MGG_Selector influences visual appearance of the whole GUI object. Graphics interfaces provided by codecs are placed as pages of a MUI page group. Then one needs a gadget for flipping those pages. It may be either a list, or a cycle gadget, as shown below:

   

The form shown on the left uses cycle gadget for format selection. This style is more compact. On the other hand, list format selection has an advantage of showing immediately the choice of formats. In case of cycle gadget, user has to click it, to get a popup menu. Cycle selector is recommended only in case where space for GUI is limited (for example in custom filerequesters).

The object returned is a subclass of MUI Group class. As such it can have a frame and background assigned if needed. In the example code it has the standard group frame and group background (the frame is not shown on pictures above). The object is usually added to application's GUI as a value of some MUIA_Group_Child tag. In most cases it is created statically at application initialization. Zormanita and U1Synth create this object statically. It can be also created dynamically, for example as an element of dynamic window. All typical MUI techniques apply.

Building Reggae Processing Chain

Memory Bufer as Data Source

Data contained in a memory buffer need some work to be used as a Reggae source. It need two Reggae objects to handle it. The first object is an instance of memory.stream class. At its output Reggae sees a stream of bytes, without further meaning or structure. Then we have to tell Reggae, it is not just a stream of bytes, but stream of audio samples with given type, number of channels, sampling rate and so on. This is done with rawaudio.filter object.

While it looks unnecessarily complicated, it allows for more freedom. By changing memory.stream to file.stream one can fetch audio data from mass storage, so is not limited by available memory. It also should be noted that both memory.stream and rawaudio.filter are just wrappers. They do not introduce any processing overhead or unnecessary data copying. Reggae stream using a buffer in memory is created as follows:

Object *stream;
QUAD stream_length = 88200;

stream = NewObject(NULL, "memory.stream",
  MMA_Stream_Handle, (IPTR)Buffer,
  MMA_Stream_Length, (IPTR)&stream_length,
TAG_END);

As the MMA_Stream_Length attribute takes QUAD number, it has to be passed via pointer. Length must be specified for memory.stream, as it has no natural end, like for example file.stream. Of course memory.stream class has to be opened previously with OpenLibrary(), as described here.