Created by Jijith Nadumuri at 28 Apr 2010 12:21 and updated at 28 Apr 2010 12:56

DirectMusic Interfaces

DirectMusic is one of the audio APIs of DirectX, the other one being DirectSound. DirectMusic does much more than simply play sounds. It provides a complete system for implementing a dynamic soundtrack that takes advantage of hardware acceleration, DLS, DMOs, and advanced 3-D positioning effects. Using DirectMusic you can load and play sounds from files or resources in MIDI, WAV, or DirectMusic Producer run-time format or schedule the timing of musical events with high precision. If the the sound-source is from DirectMusic Producer, you can do much more:- play music that varies subtly each time it repeats, compose wholly new pieces of music at run time etc.

Root Interfaces

IDirectMusic8

The IDirectMusic8 is one of the root Interfaces of DirectMusic. It represents the whole of DirectMusic API. However, unlike other similar interfaces like IDirect3D, IDirectSound8, IDirectInput etc, a programmer can choose not to use IDirectMusic8 interface and still develop his DirectMusic application.

The IDirectMusic8 interface provides methods for creating music-ports and music buffers. It can activate or deactivate a music-port. It also manages the master clock, that provide time reference while playing or creating music.

IDirectMusic8 can be used to connect DirectMusic to a DirectSound device.

Creation methods:-
CoCreateInstance Using the IID
IDirectMusicPerformance8::Init Using a performance object’s method
IDirectMusicPerformance8::InitAudio Using a performance object’s method

IDirectMusicPerformance8

The IDirectMusicPerformance8 interface represents a music performance manager. It is the overall manager of music playback. If an application needs two complete sets of music playing at the same time, it can do so by creating more than one performance, though it is a very rare case. This interface can add or remove music-ports associated with it. It controls the time flow associated with a music rendering. It manages music related messages and notifications. It can play a music segment. It can do MIDI conversions. It can create an audio path. It deals with performance channals and tool graphs.

It can create an IDirectMusic8 object and an IDirectSound8 object as part of its initialization.

Creation method:- CoCreateInstance

IDirectMusicLoader8

The IDirectMusicLoader8 interface represents a loader that loads various music objects. Loader is an object that gets other objects. It is generally one of the first objects created in a DirectMusic application. The entire loading process is carried out automatically. All you need to do is pass a description of the object to be loaded to the loader, along with a request for the corresponding interface.

Creation method:- CoCreateInstance

IDirectMusicGraph8

The IDirectMusicGraph8 represents a toolgraph. A tool graph is a collection of tools arranged as a flow chart along the time line. The tools are those tools that are used to process music related messages and notifications. The IDirectMusicGraph8 interface is used to load tools, insert them into the toolgraph or remove them from the toolgraph. It can also assign a tool to a message, so that the tool will process that message.

A message might pass through any or all of the following toolgraphs, in the order given:

• Segment toolgraph. Processes messages from a single music-segment.
• Audiopath toolgraph. Processes messages on a single audiopath.
• Performance toolgraph. Processes all messages in the performance object

Creation method:- CoCreateInstance

Interfaces for loading music objects

IDirectMusicGetLoader8

The IDirectMusicGetLoader8 represents a handle to the loader object. Assume that we have a stream of music data. The stream may refer to another musical object. We can load this new object referenced by the stream if we can get the loader associated with the stream. For this, first we query the stream object for the IDirectMusicGetLoader8 interface. Once we got the IDirectMusicGetLoader8 interface, using it we can get the loader associated with the stream.

Creation method:- QueryInterface

IDirectMusicObject8

The IDirectMusicObject8 interface represents a music related object. It is a generic interface. All DirectMusic objects that can be loaded from a file or resource, support the IDirectMusicObject8 interface so that they can work with the DirectMusic loader. New types of objects must implement this interface. Examples of music objects are bands, chordmaps, styles, musical segements and instrument collections.

Creation methods:-

QueryInterface
IDirectMusicContainer8::EnumObject.
It cannot be obtained by using CoCreateInstance.

IDirectMusicContainer8

The IDirectMusicContainer8 interface represents a collection of objects. When a container object is loaded, it makes all its objects available to the loader. When the container is released, all objects it refers to are released from the loader. However, any objects still in use when the container is released are not freed until explicitly released. As a result, the container file stays locked.

Creation methods:-
IDirectMusicLoader8::GetObject
IDirectMusicLoader8::LoadObjectFromFile.

Interfaces to compose dynamic music

IDirectMusicComposer8

The IDirectMusicComposer8 interface represents the composition engine. It can create new music-segments at run-time using chordmaps and templates. It can generate musical-transitions between different music-segments. It can also apply a chordmap to an existing segment, thus altering the chord progression and the mood of the music.

A chordmap is a flowchart of chord progressions along a time line. It represents a scheme of chord progressions. A template is a music segment used in combination with a chordmap to create a new music segment in run-time. A music-transition is a smooth flow of musical notes from one music segment to another.

Creation method:-

IDirectMusicChordMap8

The IDirectMusicChordMap8 interface represents a chordmap. A chordmap is a flowchart of chord progressions along a time line. It represents a scheme of chord progressions. Chordmaps provide the composer (represented by the IDirectMusicComposer8 interface) with the information needed to create chord progressions for music-segments composed at run time. Chordmaps can also be used to change the chords in an existing segment.

The chordmaps are stored as music data files with the extension *.cdm.

Creation methods:-

IDirectMusicStyle8::GetChordMap
IDirectMusicStyle8::EnumChordMap
IDirectMusicStyle8::GetDefaultChordMap
IDirectMusicLoader8::LoadObjectFromFile

IDirectMusicBand8

The IDirectMusicBand8 interface represents a DirectMusic band object. A band is used to set the musical instrument choices and mixer settings. Bands can be stored directly in their own files or embedded in a segment's band track or in a style's band list. A band is essentially a list of settings. It contains a reference to the musical instrument to be used and settings for volume, pan and transposition of sound.

Band-settings are usually applied to one or more channels of performance (performance channels). A music segment is usually divided into parts. Each part is routed to be played in a performance channel. Each performance channel has its own instrument and audio settings (settings for pan, volume, transposition etc). Each performance channel will be mapped to an individual audio path.

The bands are stored as music data files with the extension *.bnd.

Creation methods:-

IDirectMusicStyle8::GetBand
IDirectMusicStyle8::EnumBand
IDirectMusicStyle8::GetDefaultBand
IDirectMusicLoader8::LoadObjectFromFile

IDirectMusicStyle8

The IDirectMusicStyle8 interface represents a musical style object. A style is a collection of chordmaps, bands, musical patterns and motifs used in run-time composition of musical segments. It defines the basic rhythm and the notes to be played in each instrument part.

The styles are stored as music data files with the extension *.sty.

Creation method:-
IDirectMusicLoader8:: GetObject
IDirectMusicSegment8::GetParam

IDirectMusicCollection8

The IDirectMusicCollection8 interface represents a collection of musical instruments (DLS Collection). The collection manages an instance of a DLS file. This file contains the list and atrributes of all the instruments. The collection can enumerate all the instruments it contains and create each of them.

The DLS musical instrument collections are stored as music data files with the extension *.dls.

Creation method:- IDirectMusicLoader8:: GetObject

IDirectMusicInstrument8

The IDirectMusicInstrument8 interface represents an individual musical instrument in a collection of musical instruments (DLS Collection). A collection can create an instrument. Once an instrument is created it can be downloaded to a port (synsthesizer) by a performance object. The port can download an instrument by itself also. Once an instrument is donwloaded on a port it can be accessed only by a IDirectMusicDownloadedInstrument8 object. This object is used to release the instrument after playback.

Creation method:- IDirectMusicCollection8::GetInstrument

IDirectMusicSegment8

The IDirectMusicSegment8 interface represents a music segment, which is a playable unit of data made up of multiple music-tracks. Each segment is made up of one or more music tracks. Tracks contain most of the data for the segment. The tracks constituting a segment are managed through the segment object.

The music segments are stored as music data files with the extension *.sgt.

Creation methods:-
CoCreateInstance
IDirectMusicBand8::CreateSegment
IDirectMusicPatternTrack8::CreateSegment
IDirectMusicStyle8::GetMotif:- creates a motif-segment
Segments are created at run time by IDirectMusicComposer8 by its various methods.
Most segments are created by loading (by a loader-object) a file or resource object that supports the IDirectMusicSegment8 interface

IDirectMusicSegmentState8

The IDirectMusicSegmentState8 interface represents a playing instance of a music segment. The performance object that handles a segment, will automatically creates the segment state object, as soon as the segment starts playing, to know about the state of the playing segment.

Creation method:-
IDirectMusicSegment8::InitPlay:- normally called by perormance object, not by a programmer.
QueryInterface

IDirectMusicTrack8

The IDirectMusicTrack8 interface represents a music track, which can store any kind of data for a segment. The methods of this interface are typically not called directly by applications. However, if you want to install your own data playback mechanism in DirectMusic, you must create a track object to represent it. Usiaully the methods of this interface are called by the performance object that plays a segment.

The tracks can be of various types such as lyrics-tracks (used to synchronize words with music), marker-tracks (holds valid start times marks for the segment), motif traks (used to play motifs to accompany other segments) pattern track (contains a single musical pattern) etc.

Creation method:- QueryInterface

IDirectMusicPatternTrack8

The IDirectMusicPatternTrack8 interface represents a pattern-track, a track that contains a single pattern.

Creation method:-

Pass IID_IDirectMusicPatternTrack to the IDirectMusicTrack8::QueryInterface method of an existing track object.

Music flow related interfaces

IDirectMusicAudioPath8

The IDirectMusicAudioPath8 interface represents a path followed by music data. This interface manages the stages of music data flow from the performance object to the final mixer. An audiopath might include the performance object, a music segment, toolgraphs, the synthesizer (Microsoft software synthesizer – a music port), DirectSound (secondary) buffers, effects DMOs, and the primary DirectSound buffer where the final mixing is done.

If your application does nothing more complicated than playing 2-D sound effects or MIDI files, you can set up a standard default audiopath and play everything on it. But to take advantage of the full power of DirectMusic you may want to use multiple audiopaths and exercise more control over them.

Audiopaths use only the Microsoft software synthesizer. If you want your application to use another port or ports you must do additional settings.

IDirectMusicPort8

The IDirectMusicPort8 represents a music port (or a device which act as a port) that sends or receives sound data. A single port cannot both capture and render data. The port can be a hardware device or a software device. The Microsoft software synthesizer is a software device that act as a music port. Many IHV (Independent Hardware Vendors) -provided filters act as software music ports. MPU-401 is a hardware music port device. It has got a music input port and a music output port.

A Port is used to read data into a music buffer or to take out data from it. A port can download a musical instrument on to it. It can also deal with MIDI channels.

Creation method:- IDirectMusic8::CreatePort

IDirectMusicBuffer8

The IDirectMusicBuffer8 interface represents a music buffer containing time-stamped music data (typically in the form of MIDI messages) being sequenced to a port. The buffer contains a small amount of data, typically less than 200 milliseconds. Unless your application is doing its own sequencing, you do not need to use the methods of this interface. After a buffer is passed to a port, it cannot be reused, untill the port finishes its read/write activity on the buffer.

Creation method:- IDirectMusic8::CreateBuffer

IDirectMusicPortDownload8

The IDirectMusicPortDownload8 represents a downloader that download music-data onto a music port. This interface enables an application to communicate directly with a port, to download memory chunks directly to the port. The interface is not used unless your application is an authoring application that edit DLS instruments directly. The memory chunk is usally an instrument defenition or a waveform, which will be used to create a musical instrument. In other words, the chuck is nothing but raw instrument data. The port onto which the chunk is downloaded is usually a DLS synthesizer port.

DLS stands for DownLoadable Sound. It is a standard used for synthesizing wave sounds from digital samples stored in software. DLS level 1 and DLS level 2 standards are published by MIDI Manufacturers Association. Most of the sound data handled by DirectMusic is DLS sound data. It can be used as a synonym for the sound data, manipulated by DirectMusic.

Creation method:- QueryInterface

IDirectMusicDownload8

The IDirectMusicDownload8 interface represents a contiguous memory chunk that is being downloaded on a DLS synthesizer port by a downloader. The synthesizer may later convert it into an instrument.

This interface is used only by applications that need to manipulate sound data directly rather than letting the high level objects like performance, band, and segment do the work.

Creation method:- IDirectMusicPortDownload8::AllocateBuffer

IDirectMusicDownloadedInstrument8

The IDirectMusicDownloadedInstrument8 is used to identify an instrument that was downloaded to the synthesizer port. The instrument could be some memory chunk downloaded by a downloader. Alternativley, it could be a high level instrument dowloaded by the port itself or by a performance object.

Creation methods:-
IDirectMusicPort8::DownloadInstrument
IDirectMusicPerformance8::DownloadInstrument

IDirectMusicThru8

The IDirectMusicThru8 interface represents an interconnection between two ports. This interface supports thruing or passing of MIDI messages (events) from a capture port to another port like a render port. It is obtained by calling QueryInterface on the IDirectMusicPort8 interface object representing the capture port.

Thruing to the Microsoft software synthesizer or other synthesizers that do not have a constant latency is not recommended. Thruing is done as soon as possible upon reception of the incoming MIDI events. Because of the comparatively high latency of the software synthesizer (compared with a hardware port), each event is delayed by a small, essentially random amount of time before it plays. This random offset shows up as jitter in the playback of the data. Latency of hardware devices (such as an MPU-401 port) is small enough that jitter does not occur.

Creation method:- QueryInterface

IDirectMusicSynth

The IDirectMusicSynth interface represents a music synthesizer. This interface is implemented by applications that auther music synthesizers. Ordinary applications do not use this interface. Instead they communicate with the music port (which, in most cases, is the Microsoft software syntersizer) by using IDirectMusicPort8.

IDirectMusicSynthSink

The IDirectMusicSynthSink represents a music syntesizer sink which pull data from a synthesizer. The synsthesizer outputs the synthesized music-data onto the sink. This interface is implemented by applications that auther music synthesizers. Ordinary applications do not use this interface. In ordinary application, the finaly boundary of music data is the port. The flow of music data, through the synthesizer and the sink is beyond the reach of an ordinary application.

Other Interfaces

IDirectMusicTool8

The IDirectMusicTool8 interface reprsents a music-message processiong tool. Such a tool is used to process messages related to the events that occur during the playback or composition of music.

Methods of this interface are implemented by programmers who develop COM components that represnts such tools. In an ordinary application, they are called by the performance object. The application only needs to insert the tool in the message path. This is done by a toolgraph object, represented by the IDirectMusicGraph8 interface.

The tool might alter the message and then pass it on to the next tool, or free the message, or send a new message based on information in the old one. DirectMusic has an output tool that is normally the last to receive messages. This tool converts performance-messages to standard MIDI-messages and streams them to the synthesizer. Other tools are implemented by the application or obtained from libraries.

Creation methods:-

QueryInterface
IDirectMusicGraph8::GetTool
IDirectMusicTool8::Clone

IDirectMusicScript8

The IDirectMusicScript8 interface represents an audio script containing music related variables that can be set or read by the application, and routines that can be called by the application.

Typically the interface is obtained by using loader object to load a script file. The application then calls the init method of the IDirectMusicScript8 interface to associate the script with the performance object that performs the actual playback.

The script is stored as a script file.

Creation methods:-

IDirectMusicLoader8::GetObject:- has to give the inteface ID
IDirectMusicLoader8::LoadObjectFromFile:- has to give the class ID and inteface ID

IKsControl

The IKsControl interface is used for controlling (get, set or query) a set of properties of DirectMusic ports. The properties of a music port forms a property set. This interface is obtained by calling QueryInterface on the IDirectMusicPort8 interface object representing the port.

Request of a Property item to a port that represents a pluggable software synthesizer is answered totally in user mode (as against kernal mode). The topology of this type of port is a synthesizer (represented by an IDirectMusicSynth interface) connected to a sink node (an IDirectMusicSynthSink interface). The property request is given first to the synthesizer node, and then to the sink node if it is not recognized by the synthesizer.

Note:- The IKsControl interface is part of the WDM KS (Win32 Driver Model Kernel Streaming) architecture.

Creation method:- QueryInterface

IReferenceClock

The IReferenceClock interface represents a reference clock. A reference clock provides a common reference time for synchronization of activities. The master clock used by DirectMusic ( retrived by the IDirectMusic8::GetMasterClock method) is an instance of reference clock. The master clock is a high-resolution timer that is shared by all processes, devices, and applications that are using DirectMusic. The clock is used to synchronize all audio playback in the system. It works in kernal-mode. There is only one master clock for all DirectMusic applications. Master clock’s basic time-tick is 100 nanoseconds in duration.

This clock is based on a hardware timer. DirectMusic automatically selects the system clock as the master clock, but an application can select a different one, such as the wave-out crystal on a sound card.

It is used in DirectMusic as well as in DirectShow. Filters in a filter graph are synchronized by using a common reference time provided by a reference clock. A filter is a software component that generate, transform or consume data (usually audio, video or multimedia data). A filter-graph is a collection of such filters arranged in a flow-chart mode to perform a specific task upon the data flowing through those filters.

Applications can use IReferenceClock interface to get the current reference time, or to request notification of an elapsed time. Only programmers who develop COM components to implement filters use this interface and its methods.

Creation method:-

IDirectMusic8::GetMasterClock

Share:-