MusicSequence Reference

Audio & Video: Audio

2009-11-25

Apple Inc. 2009 Apple Inc. All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, mechanical, electronic, photocopying, recording, or otherwise, without prior written permission of Apple Inc., with the following exceptions: Any person is hereby authorized to store documentation on a single computer for personal use only and to print copies of documentation for personal use provided that the documentation contains Apples copyright notice. The Apple logo is a trademark of Apple Inc. No licenses, express or implied, are granted with respect to any of the technology described in this document. Apple retains all intellectual property rights associated with the technology described in this document. This document is intended to assist application developers to develop applications only for Apple-labeled computers. Apple Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010 Apple, the Apple logo, Mac, and Mac OS are trademarks of Apple Inc., registered in the United States and other countries.
Even though Apple has reviewed this document, APPLE MAKES NO WARRANTY OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS DOCUMENT, ITS QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. AS A RESULT, THIS DOCUMENT IS PROVIDED AS IS, AND YOU, THE READER, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND ACCURACY. IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT OR INACCURACY IN THIS DOCUMENT, even if advised of the possibility of such damages. THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL OR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer, agent, or employee is authorized to make any modification, extension, or addition to this warranty. Some states do not allow the exclusion or limitation of implied warranties or liability for incidental or consequential damages, so the above limitation or exclusion may not apply to you. This warranty gives you specific legal rights, and you may also have other rights which vary from state to state.

Contents
MusicSequence Reference 5
Overview 5 Functions by Task 5 Creating and Configuring Music Sequences 5 Working with Music Tracks 6 Working With Audio Processing Graphs and MIDI Endpoints 6 Working With Time 6 Working With Files 7 Functions 7 DisposeMusicSequence 7 MusicSequenceBarBeatTimeToBeats 8 MusicSequenceBeatsToBarBeatTime 8 MusicSequenceDisposeTrack 9 MusicSequenceFileCreate 10 MusicSequenceFileCreateData 11 MusicSequenceFileLoad 12 MusicSequenceFileLoadData 12 MusicSequenceGetAUGraph 13 MusicSequenceGetBeatsForSeconds 14 MusicSequenceGetIndTrack 15 MusicSequenceGetInfoDictionary 15 MusicSequenceGetSecondsForBeats 16 MusicSequenceGetSequenceType 16 MusicSequenceGetSMPTEResolution 17 MusicSequenceGetTempoTrack 17 MusicSequenceGetTrackCount 18 MusicSequenceGetTrackIndex 19 MusicSequenceNewTrack 19 MusicSequenceReverse 20 MusicSequenceSetAUGraph 20 MusicSequenceSetMIDIEndpoint 21 MusicSequenceSetSequenceType 21 MusicSequenceSetSMPTEResolution 22 MusicSequenceSetUserCallback 23 NewMusicSequence 23 Callbacks 24 MusicSequenceUserCallback 24 Data Types 25 MusicSequence 25 MusicTimeStamp 25 Constants 25

3
2009-11-25 | 2009 Apple Inc. All Rights Reserved.

CONTENTS

Music Sequence Load Flags 25 Music Sequence Types 26 Music Sequence File Type Identifiers 26 Music Sequence File Flags 27

Document Revision History 29

4
2009-11-25 | 2009 Apple Inc. All Rights Reserved.

MusicSequence Reference

Framework: Declared in

AudioToolbox/MusicPlayer.h MusicPlayer.h

Overview
A music sequence contains one or more music tracks, and can be played using a music player. Music tracks, in turn, can contain MIDI data and audio unit parameter automation data. A music sequence is an opaque MusicSequence data type. The opaque types used with a music sequence are described in the following documents:

MusicEventIterator Reference MusicPlayer Reference MusicTrack Reference

Result codes for this opaque type are described in MusicPlayer Reference.

Functions by Task

Creating and Configuring Music Sequences

NewMusicSequence (page 23)

Creates a new empty music sequence.

DisposeMusicSequence (page 7)

Disposes of a music sequence.

MusicSequenceSetSequenceType (page 21)

Sets the sequence type for a music sequence.

MusicSequenceGetSequenceType (page 16)

Gets the sequence type for a music sequence.

MusicSequenceSetSMPTEResolution (page 22)

Calculates the SMPTE resolution for a specified frame rate and number of ticks per quarter note.

Overview
2009-11-25 | 2009 Apple Inc. All Rights Reserved.

MusicSequence Reference

MusicSequenceGetSMPTEResolution (page 17)

Calculates the frame rate and number of ticks per quarter note for a specified SMPTE resolution.
MusicSequenceSetUserCallback (page 23)

Registers a user callback function with a music sequence.

MusicSequenceGetInfoDictionary (page 15)

Returns a dictionary containing music sequence information.

Working with Music Tracks

MusicSequenceNewTrack (page 19)

Add a new, empty music track to a music sequence.

MusicSequenceDisposeTrack (page 9)

Removes a music track from a music sequence, and disposes of the track.
MusicSequenceGetTrackCount (page 18)

Gets the number of music tracks owned by a music sequence.

MusicSequenceGetIndTrack (page 15)

Gets the music track at the specified track index.

MusicSequenceGetTrackIndex (page 19)

Gets the index number for a specified music track.

MusicSequenceGetTempoTrack (page 17)

Gets the tempo track for a music sequence.

Working With Audio Processing Graphs and MIDI Endpoints

MusicSequenceSetAUGraph (page 20)

Associates an audio processing graph with a music sequence.

MusicSequenceGetAUGraph (page 13)

Gets the audio processing graph associated with a music sequence.

MusicSequenceSetMIDIEndpoint (page 21)

Associates a specified MIDI endpoint with all music tracks in a music sequence.

Working With Time

MusicSequenceGetSecondsForBeats (page 16)

Calculates the number of seconds that correspond to a number of beats.

MusicSequenceGetBeatsForSeconds (page 14)

Calculates the number of beats that correspond to a number of seconds.

Functions by Task
2009-11-25 | 2009 Apple Inc. All Rights Reserved.

MusicSequence Reference

MusicSequenceBeatsToBarBeatTime (page 8)

Formats a music sequences beat time to its bar-beat time.

MusicSequenceBarBeatTimeToBeats (page 8)

Formats a music sequences bar-beat time to its beat time.

MusicSequenceReverse (page 20)

Reverses the MIDI and tempo events in a music sequence, so the start becomes the end.

Working With Files

MusicSequenceFileLoad (page 12)

Loads data into a music sequence from a URL reference.

MusicSequenceFileLoadData (page 12)

Load data into a music sequence from a data reference.

MusicSequenceFileCreate (page 10)

Creates a MIDI file from the events in a music sequence.

MusicSequenceFileCreateData (page 11)

Creates a data object containing the events from a music sequence.

Functions
DisposeMusicSequence
Disposes of a music sequence.
OSStatus DisposeMusicSequence ( MusicSequence inSequence );

Parameters
inSequence

The music sequence to dispose of. Return Value A result code. Discussion You cannot dispose of a music sequence while it is associated with a music player. Availability Available in Mac OS X v10.0 and later. See Also
NewMusicSequence (page 23)

Related Sample Code PlaySequence

Functions
2009-11-25 | 2009 Apple Inc. All Rights Reserved.

MusicSequence Reference

Declared In
MusicPlayer.h

MusicSequenceBarBeatTimeToBeats
Formats a music sequences bar-beat time to its beat time.
OSStatus MusicSequenceBarBeatTimeToBeats( MusicSequence inSequence, const CABarBeatTime *inBarBeatTime, MusicTimeStamp *outBeats );

Parameters
inSequence

The music sequence that you want the beat count for.
inBarBeatTime

The bar-beat time to be represented as beats.

outBeats

On output, the music sequences beat time. Return Value A result code. Discussion The sequence's tempo track time signature events are used to to calculate the bar-beat representation. If there are no Time Sig events added to the sequence 4/4 is assumed. A time signature event is a MIDI Meta Event as specified for MIDI files. Refer to AudioToolbox/CAClock.h for more information. Availability Available in Mac OS X v10.5 and later. See Also
MusicSequenceBeatsToBarBeatTime (page 8)

Declared In
MusicPlayer.h

MusicSequenceBeatsToBarBeatTime
Formats a music sequences beat time to its bar-beat time.

Functions
2009-11-25 | 2009 Apple Inc. All Rights Reserved.

MusicSequence Reference

OSStatus MusicSequenceBeatsToBarBeatTime( MusicSequence inSequence, MusicTimeStamp inBeats, UInt32 inSubbeatDivisor, CABarBeatTime *outBarBeatTime );

Parameters
inSequence

The music sequence that you want bar-beat time for.

inBeats

The beats to be represented as bar-beats.

inSubbeatDivisor

The denominator of the fractional number of beats.

outBarBeatTime

On output, the music sequences bar-beat time. Return Value A result code. Discussion The sequence's tempo track time signature events are used to to calculate the bar-beat representation. If there are no Time Sig events added to the sequence 4/4 is assumed. A time signature event is a MIDI Meta Event as specified for MIDI files. Refer to AudioToolbox/CAClock.h for more information. Availability Available in Mac OS X v10.5 and later. See Also
MusicSequenceBarBeatTimeToBeats (page 8)

Declared In
MusicPlayer.h

MusicSequenceDisposeTrack
Removes a music track from a music sequence, and disposes of the track.
OSStatus MusicSequenceDisposeTrack ( MusicSequence inSequence, MusicTrack inTrack );

Parameters
inSequence

The music sequence to remove the music track from.

inTrack

The music track to remove and dispose of. Return Value A result code.

Functions
2009-11-25 | 2009 Apple Inc. All Rights Reserved.

MusicSequence Reference

Availability Available in Mac OS X v10.0 and later. See Also

MusicSequenceNewTrack (page 19)

Declared In
MusicPlayer.h

MusicSequenceFileCreate
Creates a MIDI file from the events in a music sequence.
OSStatus MusicSequenceFileCreate ( MusicSequence inSequence, CFURLRef inFileRef, MusicSequenceFileTypeID inFileType, MusicSequenceFileFlags inFlags, SInt16 inResolution );

Parameters
inSequence

The music sequence that you want to create a MIDI file from.
inFileRef

The URL to the MIDI file to be created.

inFileType

The type of file to create.

inFlags

Flags that configure the file creation process.

inResolution

The resolution, which depends on the file type and the music sequence type. Return Value A result code. Discussion This function can be (and is most commonly) used to create a MIDI file from the events in a sequence. Only MIDI based events are used when creating the MIDI file. MIDI files are normally beat based, but can also have a SMPTE (or real-time rather than beat time) representation. The inResolution parameter specifies the relationship between "tick" and quarter note for saving to a standard MIDI file. Pass 0 to this parameter to use the default value; namely, the value that is currently set on the tempo track. The various sequence types determine the kinds of files that can be created, as follows:

BeatsWhen saving a MIDI file, it saves a beats (PPQ) based axis. SecondsWhen saving a MIDI file, it will save it as a SMPTE resolution - so you should specify this resolution when creating the MIDI file. If zero is specified, 25 fps and 40 ticks/frame is used (a time scale of a millisecond)

10

Functions
2009-11-25 | 2009 Apple Inc. All Rights Reserved.

MusicSequence Reference

SamplesYou cannot save to a MIDI file with this sequence type.

The complete meaning of the 16-bit "division" field in a MIDI File's MThd chunk. If it is positive, then a tick represents 1/D quarter notes. If it negative, the following pertains:

Bits 14-8 are a signed 7-bit number representing the SMPTE format: 24, -25, -29 (drop), -30. Bits 7-0 represents the number of ticks per SMPTE frame. Typical values are 4, 10, 80, 100. You can obtain millisecond resolution by specifying 25 frames/sec and 40 divisions/frame:
30 fps with 80 bits (ticks) per frame: 0xE250 ((char)0xE2 == -30)

Availability Available in Mac OS X v10.5 and later. See Also

MusicSequenceFileCreateData (page 11) MusicSequenceSetSMPTEResolution (page 22)

Declared In
MusicPlayer.h

MusicSequenceFileCreateData
Creates a data object containing the events from a music sequence.
OSStatus MusicSequenceFileCreateData ( MusicSequence inSequence, MusicSequenceFileTypeID inFileType, MusicSequenceFileFlags inFlags, SInt16 inResolution, CFDataRef *outData );

Parameters
inSequence

The music sequence that you want to create a MIDI data object from.
inFileType

The type of file format for the data in the data object.
inFlags

Flags that configure the data object creation process.

inResolution

The resolution, which depends on the file type and the music sequence type.
outData

On output, the data object containing MIDI data in the specified format. Return Value A result code. Discussion The CFData object should be released by the caller.

Functions
2009-11-25 | 2009 Apple Inc. All Rights Reserved.

11

MusicSequence Reference

Availability Available in Mac OS X v10.5 and later. See Also

MusicSequenceFileCreate (page 10)

Declared In
MusicPlayer.h

MusicSequenceFileLoad
Loads data into a music sequence from a URL reference.
OSStatus MusicSequenceFileLoad ( MusicSequence inSequence, CFURLRef inFileRef, MusicSequenceFileTypeID inFileTypeHint, // can be zero in many cases MusicSequenceLoadFlags inFlags );

Parameters
inSequence

The music sequence to load the data into.

inFileRef A file:// URL pointing to a file that contains the data to load. inFileTypeHint

Provides a hint to the system about the file type referenced by the inFileRef parameter.
inFlags

Flags that specify how the data should be parsed, and how it should be assigned to tracks. See Music Sequence Load Flags (page 25). Return Value A result code. Availability Available in Mac OS X v10.5 and later. See Also
MusicSequenceFileLoadData (page 12)

Related Sample Code PlaySequence Declared In

MusicPlayer.h

MusicSequenceFileLoadData
Load data into a music sequence from a data reference.

12

Functions
2009-11-25 | 2009 Apple Inc. All Rights Reserved.

MusicSequence Reference

OSStatus MusicSequenceFileLoadData ( MusicSequence inSequence, CFDataRef inData, MusicSequenceFileTypeID inFileTypeHint, // can be zero in many cases MusicSequenceLoadFlags inFlags );

Parameters
inSequence

The music sequence to load the data into.

inData

The contents of a valid file loaded into a CFData object.

inFileTypeHint

Provides a hint to the system about the file type referenced by the inFileRef parameter.
inFlags

Flags that specify how the data should be parsed, and how it should be assigned to tracks. See Music Sequence Load Flags (page 25). Return Value A result code. Discussion The data to be loaded must conform to the file type indicated by the inFileTypeHint parameter. Availability Available in Mac OS X v10.5 and later. See Also
MusicSequenceFileLoad (page 12)

Declared In
MusicPlayer.h

MusicSequenceGetAUGraph
Gets the audio processing graph associated with a music sequence.
OSStatus MusicSequenceGetAUGraph ( MusicSequence inSequence, AUGraph *outGraph );

Parameters
inSequence

The music sequence whose associated audio processing graph you want to get.
outGraph

On output, the audio processing graph associated with the music sequence. Return Value A result code.

Functions
2009-11-25 | 2009 Apple Inc. All Rights Reserved.

13

MusicSequence Reference

Discussion If no audio processing graph is already associated with the music sequence, this function creates a default graph. The default graph contains an Instrument unit (of type DLSMusicDevice) and a dynamic compressor unit (of type DynamicCompressor). In this case, all music tracks in the music sequence have their outputs directed to the Instrument unit. Availability Available in Mac OS X v10.0 and later. See Also
MusicSequenceSetAUGraph (page 20)

Related Sample Code PlaySequence Declared In

MusicPlayer.h

MusicSequenceGetBeatsForSeconds
Calculates the number of beats that correspond to a number of seconds.
OSStatus MusicSequenceGetBeatsForSeconds ( MusicSequence inSequence, Float64 inSeconds, MusicTimeStamp *outBeats );

Parameters
inSequence

The sequence that you want to get a count of beats for.

inSeconds

The number of seconds that you want the corresponding number of beats for.
outBeats

On output, the number of beats that corresponds to the number of seconds in the inSeconds parameter. Return Value A result code. Discussion This function makes use of the music sequences tempo track. Availability Available in Mac OS X v10.2 and later. See Also
MusicSequenceGetSecondsForBeats (page 16)

Declared In
MusicPlayer.h

14

Functions
2009-11-25 | 2009 Apple Inc. All Rights Reserved.

MusicSequence Reference

MusicSequenceGetIndTrack
Gets the music track at the specified track index.
OSStatus MusicSequenceGetIndTrack ( MusicSequence inSequence, UInt32 inTrackIndex, MusicTrack *outTrack );

Parameters
inSequence

The music sequence to obtain the music track from.

inTrackIndex

The whole-number index for the music track you want to obtain. This function returns an error if the value for this parameter is not greater than 0 and less than the number of music tracks.
outTrack

On output, the music track specified by the inTrackIndex parameter. Return Value A result code. Discussion This function is for accessing only music tracks, not the tempo track. Availability Available in Mac OS X v10.0 and later. See Also
MusicSequenceGetTrackIndex (page 19)

Related Sample Code PlaySequence Declared In

MusicPlayer.h

MusicSequenceGetInfoDictionary
Returns a dictionary containing music sequence information.
CFDictionaryRef MusicSequenceGetInfoDictionary ( MusicSequence inSequence );

Parameters
inSequence

The music sequence that you want the information dictionary from. Return Value A dictionary object containing information about a music sequence.

Functions
2009-11-25 | 2009 Apple Inc. All Rights Reserved.

15

MusicSequence Reference

Discussion The dictionary can contain one or more of the kAFInfoDictionary_* keys specified in AudioToolbox/AudioFile.h. The caller should release the returned dictionary. If the call fails it will return
NULL

Availability Available in Mac OS X v10.5 and later. Declared In

MusicPlayer.h

MusicSequenceGetSecondsForBeats
Calculates the number of seconds that correspond to a number of beats.
OSStatus MusicSequenceGetSecondsForBeats ( MusicSequence inSequence, MusicTimeStamp inBeats, Float64 *outSeconds );

Parameters
inSequence

The sequence that you want to get a count of seconds for.

inBeats

The number of beats that you want the corresponding number of seconds for.
outSeconds

On output, the number of seconds that corresponds to the number of beats in the inBeats parameter. Return Value A result code. Discussion This function makes use of the music sequences tempo track. Availability Available in Mac OS X v10.2 and later. See Also
MusicSequenceGetBeatsForSeconds (page 14)

Declared In
MusicPlayer.h

MusicSequenceGetSequenceType
Gets the sequence type for a music sequence.

16

Functions
2009-11-25 | 2009 Apple Inc. All Rights Reserved.

MusicSequence Reference

OSStatus MusicSequenceGetSequenceType ( MusicSequence inSequence, MusicSequenceType *outType );

Parameters
inSequence

The music sequence whose sequence type you want to get.

outType

On output, the sequence type for the music sequence. Return Value A result code. Availability Available in Mac OS X v10.5 and later. See Also
MusicSequenceSetSequenceType (page 21)

Declared In
MusicPlayer.h

MusicSequenceGetSMPTEResolution
Calculates the frame rate and number of ticks per quarter note for a specified SMPTE resolution.
MusicSequenceGetSMPTEResolution ( SInt16 inRes, SignedByte *fps, Byte *ticks );

Parameters
inRes

The SMPTE resolution of a MIDI file.

fps

Frames per second.

ticks

Ticks per quarter note. See Also

MusicSequenceFileCreate (page 10) MusicSequenceSetSMPTEResolution (page 22)

MusicSequenceGetTempoTrack
Gets the tempo track for a music sequence.

Functions
2009-11-25 | 2009 Apple Inc. All Rights Reserved.

17

MusicSequence Reference

OSStatus MusicSequenceGetTempoTrack ( MusicSequence inSequence, MusicTrack *outTrack );

Parameters
inSequence

The music sequence whose tempo track you want to obtain.

outTrack

On output, the tempo track. Return Value A result code. Discussion Each music sequence has a single tempo track. All tempo events are placed into this track, as well as some other eventssuch as the time signature from a MIDI file. The tempo track, once retrieved, can be edited and iterated over as can a music track. Most non-tempo events in a tempo track are ignored. Availability Available in Mac OS X v10.1 and later. Declared In
MusicPlayer.h

MusicSequenceGetTrackCount
Gets the number of music tracks owned by a music sequence.
OSStatus MusicSequenceGetTrackCount ( MusicSequence inSequence, UInt32 *outNumberOfTracks );

Parameters
inSequence

The music sequence whose track count you want.

outNumberOfTracks

On output, the number of music tracks in the music sequence. Return Value A result code. Discussion The track count provided by this function excludes the tempo track. Availability Available in Mac OS X v10.0 and later. Related Sample Code PlaySequence Declared In
MusicPlayer.h

18

Functions
2009-11-25 | 2009 Apple Inc. All Rights Reserved.

MusicSequence Reference

MusicSequenceGetTrackIndex
Gets the index number for a specified music track.
OSStatus MusicSequenceGetTrackIndex ( MusicSequence inSequence, MusicTrack inTrack, UInt32 *outTrackIndex );

Parameters
inSequence

The music sequence to obtain the track index number from.

inTrack

The music track whose index you want to obtain. This function returns an error if the music track is not part of the music sequence specified in the inSequence parameter.
outTrackIndex

On output, the zero-based index of the music track that you provided in the inTrack parameter. Return Value A result code. Discussion This function is for accessing only indexes for music tracks, not the tempo track. Availability Available in Mac OS X v10.0 and later. See Also
MusicSequenceGetIndTrack (page 15)

Declared In
MusicPlayer.h

MusicSequenceNewTrack
Add a new, empty music track to a music sequence.
OSStatus MusicSequenceNewTrack ( MusicSequence inSequence, MusicTrack *outTrack );

Parameters
inSequence

The music sequence to add the new music track to.

outTrack

On output, the new music track that was appended to the list of tracks for the music sequence. Return Value A result code. Availability Available in Mac OS X v10.0 and later.

Functions
2009-11-25 | 2009 Apple Inc. All Rights Reserved.

19

MusicSequence Reference

See Also
MusicSequenceDisposeTrack (page 9)

Declared In
MusicPlayer.h

MusicSequenceReverse
Reverses the MIDI and tempo events in a music sequence, so the start becomes the end.
OSStatus MusicSequenceReverse ( MusicSequence inSequence );

Parameters
inSequence

The music sequence that you want to time-reverse. Return Value A result code. Availability Available in Mac OS X v10.0 and later. Declared In
MusicPlayer.h

MusicSequenceSetAUGraph
Associates an audio processing graph with a music sequence.
OSStatus MusicSequenceSetAUGraph ( MusicSequence inSequence, AUGraph inGraph );

Parameters
inSequence

The music sequence to associate with an audio processing graph.

inGraph

The audio processing graph to associate with the music sequence. Return Value A result code. Discussion After you call this function, the system directs a played music sequences output to the associated audio processing graph. By default, all music tracks in the sequence are directed to the first node in the graph that is an Instrument unit (of type DLSMusicDevice). Availability Available in Mac OS X v10.0 and later.

20

Functions
2009-11-25 | 2009 Apple Inc. All Rights Reserved.

MusicSequence Reference

See Also
MusicSequenceGetAUGraph (page 13)

Declared In
MusicPlayer.h

MusicSequenceSetMIDIEndpoint
Associates a specified MIDI endpoint with all music tracks in a music sequence.
OSStatus MusicSequenceSetMIDIEndpoint ( MusicSequence inSequence, MIDIEndpointRef inEndpoint );

Parameters
inSequence

The music sequence that you want to associate with a MIDI endpoint.
inEndpoint

The MIDI endpoint to associate with the music sequence. Return Value A result code. Discussion This is a convenience function, equivalent to iterating through the music tracks in a music sequence and targeting each to the MIDI endpoint. Availability Available in Mac OS X v10.1 and later. Related Sample Code PlaySequence Declared In
MusicPlayer.h

MusicSequenceSetSequenceType
Sets the sequence type for a music sequence.
OSStatus MusicSequenceSetSequenceType ( MusicSequence inSequence, MusicSequenceType inType );

Parameters
inSequence

The music sequence whose sequence type you want to set.

inType

The type of sequence to assign to the music sequence. For the list of available sequence types, see Music Sequence Types (page 26). The default sequence type is kMusicSequenceType_Beats.

Functions
2009-11-25 | 2009 Apple Inc. All Rights Reserved.

21

MusicSequence Reference

Return Value A result code. Discussion The sequence type can be set to kMusicSequenceType_Beats at any time. The sequence type can only be set to kMusicSequenceType_Seconds or kMusicSequenceType_Samples if there are no tempo events already in the sequence. The following considerations pertain to the various sequence types:

kMusicSequenceType_BeatsTempo is specified as beats-per-minute. A music sequence of this type

can contain any number of tempo events.

kMusicSequenceType_SamplesTempo is specified as a sample rate, in terms of samples-per-second.

If you set the tempo to 44,100 using a sequence of this type, then 44,100 beats corresponds to a duration of one second.

kMusicSequenceType_SecondsThe tempo should be set to 60; a beat is a second.

After setting a music sequence to the kMusicSequenceType_Samples or kMusicSequenceType_Seconds type, add a single tempo event to specify the tempo. A meta event of interest for the kMusicSequenceType_Seconds sequence type is the SMPTE Offset meta event, which is stored in the tempo track. The sequence doesn't do anything with this event. Availability Available in Mac OS X v10.5 and later. See Also
MusicSequenceGetSequenceType (page 16)

Declared In
MusicPlayer.h

MusicSequenceSetSMPTEResolution
Calculates the SMPTE resolution for a specified frame rate and number of ticks per quarter note.
SInt16 MusicSequenceSetSMPTEResolution ( SignedByte fps, Byte ticks );

Parameters
fps

Frames per second.

ticks

Ticks per quarter note. Return Value A SMPTE resolution. See Also
MusicSequenceFileCreate (page 10)

22

Functions
2009-11-25 | 2009 Apple Inc. All Rights Reserved.

MusicSequence Reference

MusicSequenceGetSMPTEResolution (page 17)

MusicSequenceSetUserCallback
Registers a user callback function with a music sequence.
OSStatus MusicSequenceSetUserCallback ( MusicSequence inSequence, MusicSequenceUserCallback inCallback, void *inClientData );

Parameters
inSequence

The music sequence that you want to add a user callback function to.
inCallback

A reference to your callback function. Use NULL to remove a registered callback function.
inClientData

Your data that the music sequence provides back to your callback function when it is invoked. Return Value A result code. Discussion The music sequence invokes your callback for each user event added to any music track owned by the sequence. If there is a callback registered, then UserEvents will be chased when MusicPlayerSetTime is called. In that case the inStartSliceBeat and inEndSliceBeat will both be the same value and will be the beat that the player is chasing to. Usually, where the sequence data is being scheduled for playback, the following applies:
inStartSliceBeat <= inEventTime < inEndSliceBeat

The only exception to this is if the track that owns the MusicEvent is looping. In this case the start beat will still be less than the end beat (so your callback can still determine that it is playing, and what beats are currently being scheduled), however, the inEventTime will be the original time-stamped time of the user event. Availability Available in Mac OS X v10.3 and later. Declared In
MusicPlayer.h

NewMusicSequence
Creates a new empty music sequence.

Functions
2009-11-25 | 2009 Apple Inc. All Rights Reserved.

23

MusicSequence Reference

OSStatus NewMusicSequence ( MusicSequence *outSequence );

Parameters
outSequence

On output, the new, empty music sequence. Return Value A result code. Discussion A new music sequence has only a tempo track, with a default tempo of 120 beats-per-minute. The default sequence type is beat-based. For the various sequence types, see Music Sequence Types (page 26). To direct the output of a music sequence to an audio processing graph, use the MusicSequenceSetAUGraph (page 20) function. To direct the output instead to a MIDI endpoint, use the MusicSequenceSetMIDIEndpoint (page 21) function. To direct the output of a specific music track, use the MusicTrackSetDestNode and MusicTrackSetDestMIDIEndpoint functions, described in MusicTrack Reference. Availability Available in Mac OS X v10.0 and later. See Also
DisposeMusicSequence (page 7)

Related Sample Code PlaySequence Declared In

MusicPlayer.h

Callbacks
MusicSequenceUserCallback
typedef void (*MusicSequenceUserCallback) ( void *inClientData, MusicSequence inSequence, MusicTrack inTrack, MusicTimeStamp inEventTime, const MusicEventUserData *inEventData, MusicTimeStamp inStartSliceBeat, MusicTimeStamp inEndSliceBeat );

If you named your callback MyMusicSequenceUserCallback, you would declare it like this:
void MyMusicSequenceUserCallback ( void *inClientData, MusicSequence inSequence,

24

Callbacks
2009-11-25 | 2009 Apple Inc. All Rights Reserved.

MusicSequence Reference

MusicTrack MusicTimeStamp const MusicEventUserData MusicTimeStamp MusicTimeStamp );

inTrack, inEventTime, *inEventData, inStartSliceBeat, inEndSliceBeat

Availability Available in Mac OS X v10.3 and later. Declared In

MusicPlayer.h

Data Types
MusicSequence
A music sequence.
typedef struct OpaqueMusicSequence *MusicSequence;

Availability Available in Mac OS X v10.0 and later. Declared In

MusicPlayer.h

MusicTimeStamp
A timestamp for use by a music sequence.
typedef Float64 MusicTimeStamp;

Availability Available in Mac OS X v10.0 and later. Declared In

MusicPlayer.h

Constants
Music Sequence Load Flags
Flags used to configure the behavior of the MusicSequenceFileLoad (page 12) and MusicSequenceFileLoadData (page 12) functions.

Data Types
2009-11-25 | 2009 Apple Inc. All Rights Reserved.

25

MusicSequence Reference

enum { kMusicSequenceLoadSMF_ChannelsToTracks = (1 << 0) }; typedef UInt32 MusicSequenceLoadFlags;

Constants
kMusicSequenceLoadSMF_ChannelsToTracks

If this flag is set the resultant Sequence will contain a tempo track, 1 track for each MIDI Channel that is found in the SMF, 1 track for SysEx or MetaEvents - and this will be the last track in the sequence after the LoadSMFWithFlags calls. Available in Mac OS X v10.3 and later. Declared in MusicPlayer.h.

Music Sequence Types

The various types of music sequences.
enum { kMusicSequenceType_Beats = 'beat', kMusicSequenceType_Seconds = 'secs', kMusicSequenceType_Samples = 'samp' }; typedef UInt32 MusicSequenceType;

Constants
kMusicSequenceType_Beats

Used for a music sequence that corresponds to a normal MIDI file. The tempo track defines the number of beats per second and can have multiple tempo events. Available in Mac OS X v10.5 and later. Declared in MusicPlayer.h.
kMusicSequenceType_Seconds

Used for a music sequence that corresponds to a MIDI file, but employs SMPTE timecode. The tempo track contains a single tempo event that specifies 60 beat-per-minute. Available in Mac OS X v10.5 and later. Declared in MusicPlayer.h.
kMusicSequenceType_Samples

Used for audio samples; a music sequence of this type cannot be saved to a MIDI file. The tempo track contains a single tempo event that specifies an audio sample rate in samples-per-second. Available in Mac OS X v10.5 and later. Declared in MusicPlayer.h.

Music Sequence File Type Identifiers

The various types of files that can be parsed by a music sequence.

26

Constants
2009-11-25 | 2009 Apple Inc. All Rights Reserved.

MusicSequence Reference

enum { kMusicSequenceFile_MIDIType = 'midi', kMusicSequenceFile_iMelodyType = 'imel' }; typedef UInt32 MusicSequenceFileTypeID;

Constants
kMusicSequenceFile_MIDIType

A MIDI file type Available in Mac OS X v10.5 and later. Declared in MusicPlayer.h.
kMusicSequenceFile_iMelodyType

An iMelody file type. Available in Mac OS X v10.5 and later. Declared in MusicPlayer.h.

Music Sequence File Flags

Flags that configure the behavior of the MusicSequenceFileCreate (page 10) and MusicSequenceFileCreateData (page 11) functions.
enum { kMusicSequenceFileFlags_EraseFile = 1 }; typedef UInt32 MusicSequenceFileFlags;

Constants
kMusicSequenceFileFlags_EraseFile

Specifies that an existing file should be erased when creating a new file. Available in Mac OS X v10.5 and later. Declared in MusicPlayer.h.

Constants
2009-11-25 | 2009 Apple Inc. All Rights Reserved.

27

MusicSequence Reference

28

Constants
2009-11-25 | 2009 Apple Inc. All Rights Reserved.

REVISION HISTORY

Document Revision History

This table describes the changes to MusicSequence Reference. Date 2009-11-25 Notes Added descriptions for the MusicSequenceSetSMPTEResolution (page 22) and MusicSequenceGetSMPTEResolution (page 17) inline functions. Other minor improvements. 2009-11-17 New document that describes a playable collection of MIDI music tracks.

29
2009-11-25 | 2009 Apple Inc. All Rights Reserved.

REVISION HISTORY

Document Revision History

30
2009-11-25 | 2009 Apple Inc. All Rights Reserved.