SSSynth

Superclass:
NSObject
Declared In:

Introduction

the interface to the synthesizer which plays the MusicXML score


Methods

-addSampledInstrument:

add a sampled instrument and return its unique identifier

-addSynthesizedInstrument:

add a synthesized instrument (metronome tick)

-changedControls

notification that the SSSyControls have changed

+createSynth:

create the synthesizer

+createSynth:score:

create the synthesizer

-pause

pause play

-removeInstrument:

remove the instrument

-reset

stop play and reset the play position to the start

-resume

resume play if paused

-setBarChangeHandler:

register an event handler to be called at the start of each bar

-setBarChangeHandler:delay:

register an event handler to be called at the start of each bar

-setBeatHandler:

register an event handler to be called on each beat in the bar

-setBeatHandler:delay:

register an event handler to be called on each beat in the bar

-setEndHandler:

register an event handler to be called on completion of play

-setEndHandler:delay:

register an event handler to be called on completion of play

-setNextBarToPlay

if the bar is within range (with the current settings including loop settings) then set the next bar to play. The synth will automatically stop play and restart at the new bar

-setNextBarToPlay:at:

if the bar is within range (with the current settings including loop settings) then set the next bar to play. The synth will automatically stop play and restart at the new bar

-setNoteHandler:

register an event handler to be called on start and end of new note/chord

-setNoteHandler:delay:

register an event handler to be called on start and end of new note/chord

-setup:

setup the synthesizer with the play data

-startAt:

start playing at the given time from the start of the given bar

-startAt:bar:countIn:

start playing at the given time from the start of the given bar

-updateTempoAt:

called on changing something which will affect the return value from SSUTempo which was supplied to the SSPData. The play tempo will update at the given time

addSampledInstrument:

add a sampled instrument and return its unique identifier 

-(sscore_sy_instrumentid)addSampledInstrument:(const sscore_sy_sampledinstrumentinfo *)info;
Parameters
info

describes the instrument including the filenames of the samples in the app resources, usually defined as a static const

addSynthesizedInstrument:

add a synthesized instrument (metronome tick) 

-(sscore_sy_instrumentid)addSynthesizedInstrument:(const sscore_sy_synthesizedinstrumentinfo *)info;
Parameters
info

description of the instrument, usually defined as a static const

changedControls

notification that the SSSyControls have changed 

-(void)changedControls;

createSynth:

create the synthesizer 

+(SSSynth*)createSynth:(id<SSSyControls>)controls score:(SSScore*)score;
Parameters
controls

the object which implements SSSyControls to control the synth (usually using UI controls, sliders, switches etc)

score

the score (used to access the key)

See Also

createSynth:score:

createSynth:score:

create the synthesizer 

+(SSSynth*)createSynth:(id<SSSyControls>)controls score:(SSScore*)score;
Parameters
controls

the object which implements SSSyControls to control the synth (usually using UI controls, sliders, switches etc)

score

the score (used to access the key)

See Also

createSynth:

pause

pause play 

-(void)pause;

removeInstrument:

remove the instrument 

-(void)removeInstrument:(sscore_sy_instrumentid)instrument;
Parameters
instrument

the id returned from addXXXInstrument

reset

stop play and reset the play position to the start 

-(void)reset;
Discussion

you need to call setup: again to play after reset

resume

resume play if paused 

-(void)resume;

setBarChangeHandler:

register an event handler to be called at the start of each bar 

-(void)setBarChangeHandler:(id<SSEventHandler>) handler 
        delay:(int)delay_ms;
Parameters
handler

the handler to be called at the start of each bar

delay_ms

a millisecond delay for the handler call, which can be negative (normally) to anticipate the bar change eg for an animated cursor

See Also

setBarChangeHandler:delay:

setBarChangeHandler:delay:

register an event handler to be called at the start of each bar 

-(void)setBarChangeHandler:(id<SSEventHandler>) handler 
        delay:(int)delay_ms;
Parameters
handler

the handler to be called at the start of each bar

delay_ms

a millisecond delay for the handler call, which can be negative (normally) to anticipate the bar change eg for an animated cursor

See Also

setBarChangeHandler:

setBeatHandler:

register an event handler to be called on each beat in the bar 

-(void)setBeatHandler:(id<SSEventHandler>) handler delay:(int)delay_ms;
Parameters
handler

the handler to be called on each beat

delay_ms

a millisecond delay for the handler call, which can be negative to anticipate the event

See Also

setBeatHandler:delay:

setBeatHandler:delay:

register an event handler to be called on each beat in the bar 

-(void)setBeatHandler:(id<SSEventHandler>) handler delay:(int)delay_ms;
Parameters
handler

the handler to be called on each beat

delay_ms

a millisecond delay for the handler call, which can be negative to anticipate the event

See Also

setBeatHandler:

setEndHandler:

register an event handler to be called on completion of play 

-(void)setEndHandler:(id<SSEventHandler>) handler delay:(int)delay_ms;
Parameters
handler

the handler to be called at the end of play

delay_ms

a millisecond delay for the handler call, which can be negative to anticipate the event

See Also

setEndHandler:delay:

setEndHandler:delay:

register an event handler to be called on completion of play 

-(void)setEndHandler:(id<SSEventHandler>) handler delay:(int)delay_ms;
Parameters
handler

the handler to be called at the end of play

delay_ms

a millisecond delay for the handler call, which can be negative to anticipate the event

See Also

setEndHandler:

setNextBarToPlay

if the bar is within range (with the current settings including loop settings) then set the next bar to play. The synth will automatically stop play and restart at the new bar 

-(bool)setNextBarToPlay:(int)barIndex at:(dispatch_time_t)restart_time;
Parameters
barIndex

the bar to jump to

restart_time

the (future) time to restart play from the start of the new bar

Return Value

false if failed

See Also

setNextBarToPlay:at:

setNextBarToPlay:at:

if the bar is within range (with the current settings including loop settings) then set the next bar to play. The synth will automatically stop play and restart at the new bar 

-(bool)setNextBarToPlay:(int)barIndex at:(dispatch_time_t)restart_time;
Parameters
barIndex

the bar to jump to

restart_time

the (future) time to restart play from the start of the new bar

See Also

setNextBarToPlay

setNoteHandler:

register an event handler to be called on start and end of new note/chord 

-(void)setNoteHandler:(id<SSNoteHandler>) handler delay:(int)delay_ms;
Parameters
handler

the handler to be called at the start and end of each note

delay_ms

a millisecond delay for the handler call, which can be negative to anticipate the event

Discussion

This can be used to move a cursor onto each note as it is played. NB for a piece with many fast notes you need to ensure your handler is fast enough to handle the throughput. You will probably define the endNote() method to do nothing as this is called for every note, unlike startNotes which is only called once per chord

See Also

setNoteHandler:delay:

setNoteHandler:delay:

register an event handler to be called on start and end of new note/chord 

-(void)setNoteHandler:(id<SSNoteHandler>) handler delay:(int)delay_ms;
Parameters
handler

the handler to be called at the start and end of each note

delay_ms

a millisecond delay for the handler call, which can be negative to anticipate the event

Discussion

This can be used to move a cursor onto each note as it is played. NB for a piece with many fast notes you need to ensure your handler is fast enough to handle the throughput. You will probably define the endNote() method to do nothing as this is called for every note, unlike startNotes which is only called once per chord

See Also

setNoteHandler:

setup:

setup the synthesizer with the play data 

-(enum sscore_error)setup:(SSPData*)playdata;
Parameters
playdata

the information about what to play

startAt:

start playing at the given time from the start of the given bar 

-(enum sscore_error)startAt:(dispatch_time_t)start_time bar:(int)barIndex 
        countIn:(bool)countIn;
Parameters
start_time

the (future) time to start playing

barIndex

the 0-based bar to start playing from

countIn

set if you want a count-in bar at the start

See Also

startAt:bar:countIn:

startAt:bar:countIn:

start playing at the given time from the start of the given bar 

-(enum sscore_error)startAt:(dispatch_time_t)start_time bar:(int)barIndex 
        countIn:(bool)countIn;
Parameters
start_time

the (future) time to start playing

barIndex

the 0-based bar to start playing from

countIn

set if you want a count-in bar at the start

See Also

startAt:

updateTempoAt:

called on changing something which will affect the return value from SSUTempo which was supplied to the SSPData. The play tempo will update at the given time 

-(void)updateTempoAt:(dispatch_time_t)restart_time;
Parameters
restart_time

the time to restart with the new tempo (at the start of the current bar)

Properties

isPaused

true if paused

isPlaying

true if playing

playingBar

the 0-based index of the bar which is currently being played

isPaused

true if paused 

@property (readonly) bool isPaused;

isPlaying

true if playing 

@property (readonly) bool isPlaying;

playingBar

the 0-based index of the bar which is currently being played 

@property (readonly) int playingBar;

 

Last Updated: Sunday, July 03, 2016