MIKMIDISynthesizer

Objective-C

@interface MIKMIDISynthesizer : NSObject <MIKMIDICommandScheduler>

Swift

class MIKMIDISynthesizer : NSObject, MIKMIDICommandScheduler

MIKMIDISynthesizer provides a simple way to synthesize MIDI messages to produce sound output.

To use it, simply create a synthesizer instance, then pass MIDI messages to it by calling -handleMIDIMessages:.

A subclass, MIKMIDIEndpointSynthesizer, adds the ability to easily connect to a MIDI endpoint and automatically synthesize incoming messages.

See

MIKMIDIEndpointSynthesizer

  • Initializes an MIKMIDISynthesizer instance which uses the default MIDI instrument audio unit.

    On OS X, the default unit is Apple’s DLS Synth audio unit. On iOS, the default is Apple’s AUSampler audio unit.

    Declaration

    Objective-C

    - (nullable instancetype)initWithError:(NSError *_Nullable *_Nullable)error;

    Swift

    convenience init(error: ()) throws

    Parameters

    error

    If an error occurs, upon returns contains an NSError object that describes the problem. If you are not interested in possible errors, you may pass in NULL.

    Return Value

    An initialized MIKMIDIEndpointSynthesizer or nil if an error occurs.

  • Initializes an MIKMIDISynthesizer instance which uses an audio unit matching the provided description.

    Declaration

    Objective-C

    - (nullable instancetype)
    initWithAudioUnitDescription:(AudioComponentDescription)componentDescription
                           error:(NSError *_Nullable *_Nullable)error;

    Swift

    init(audioUnitDescription componentDescription: AudioComponentDescription, error: ()) throws

    Parameters

    componentDescription

    AudioComponentDescription describing the Audio Unit instrument you would like the synthesizer to use.
    error

    If an error occurs, upon returns contains an NSError object that describes the problem. If you are not interested in possible errors, you may pass in NULL.

    Return Value

    An initialized MIKMIDIEndpointSynthesizer or nil if an error occurs.

  • This synthesizer’s available instruments. An array of MIKMIDISynthesizerInstrument instances.

    Note that this method currently always returns an empty array on iOS. See https://github.com/mixedinkey-opensource/MIKMIDI/issues/76

    Instruments returned by this property can be selected using -selectInstrument:

    Declaration

    Objective-C

    @property (nonatomic, readonly) NSArray<MIKMIDISynthesizerInstrument *> *_Nonnull availableInstruments;

    Swift

    var availableInstruments: [MIKMIDISynthesizerInstrument] { get }

  • Changes the instrument/voice used by the synthesizer.

    See

    +[MIKMIDISynthesizerInstrument availableInstruments]

    Declaration

    Objective-C

    - (BOOL)selectInstrument:(nonnull MIKMIDISynthesizerInstrument *)instrument
                   error:(NSError *_Nullable *_Nullable)error;

    Swift

    func selectInstrument(_ instrument: MIKMIDISynthesizerInstrument, error: ()) throws

    Parameters

    instrument

    An MIKMIDISynthesizerInstrument instance.
    error

    On failure, returns by reference an error object.

    Return Value

    YES if the instrument was successfully changed, NO if the change failed.

  • Loads the sound font (.dls or .sf2) file at fileURL.

    Declaration

    Objective-C

    - (BOOL)loadSoundfontFromFileAtURL:(nonnull NSURL *)fileURL
                             error:(NSError *_Nullable *_Nullable)error;

    Swift

    func loadSoundfontFromFile(at fileURL: URL) throws

    Parameters

    fileURL

    A fileURL for a .dls or .sf2 file.
    error

    If an error occurs, upon returns contains an NSError object that describes the problem. If you are not interested in possible errors, you may pass in NULL.

    Return Value

    YES if loading the sound font file was succesful, NO if an error occurred.

  • This is currently undocumented. Documentation contributions are always welcome!

    Declaration

    Objective-C

    + (AudioComponentDescription)appleSynthComponentDescription;

    Swift

    class func appleSynthComponentDescription() -> AudioComponentDescription

  • Sets up the AUGraph for the instrument. Do not call this method, as it is called automatically during initialization.

    The method is provided to give subclasses a chance to override the AUGraph behavior for the instrument. If you do override it, you will need to create an AudioUnit instrument and set it to the instrument property. Also, if you intend to use the graph property, you will be responsible for setting that as well. DisposeAUGraph() is called on the previous graph when setting the graph property, and in dealloc.

    Declaration

    Objective-C

    - (BOOL)setupAUGraphWithError:(NSError *_Nullable *_Nullable)error;

    Swift

    func setupAUGraphWithError() throws

    Parameters

    error

    If an error occurs, upon returns contains an NSError object that describes the problem. If you are not interested in possible errors, you may pass in NULL.

    Return Value

    YES is setting up the graph was succesful, and initialization should continue, NO if setting up the graph failed and initialization should return nil.

  • Plays MIDI messages through the synthesizer.

    This method can be used to synthesize arbitrary MIDI events. It is especially useful for MIKMIDIEndpointSynthesizers that are not connected to a MIDI endpoint.

    Declaration

    Objective-C

    - (void)handleMIDIMessages:(nonnull NSArray<MIKMIDICommand *> *)messages;

    Swift

    func handleMIDIMessages(_ messages: [MIKMIDICommand])

    Parameters

    messages

    An NSArray of MIKMIDICommand (subclass) instances.

  • The component description of the underlying Audio Unit instrument.

    Declaration

    Objective-C

    @property (nonatomic, readonly) AudioComponentDescription componentDescription;

    Swift

    var componentDescription: AudioComponentDescription { get }

  • The Audio Unit instrument that ultimately receives all of the MIDI messages sent to this endpoint synthesizer.

    Note

    You should only use the setter for this property from an MIKMIDIEndpointSynthesizer subclass.

    See

    -setupAUGraph

    Declaration

    Objective-C

    @property (nonatomic, readonly, nullable) AudioUnit instrumentUnit;

    Swift

    var instrumentUnit: AudioUnit? { get }

  • The AUGraph for the instrument.

    Note

    You should only use the setter for this property from an MIKMIDIEndpointSynthesizer subclass.

    See

    -setupAUGraph

    Declaration

    Objective-C

    @property (nonatomic, nullable) AUGraph graph;

    Swift

    var graph: AUGraph? { get set }

Deprecated

  • Deprecated

    Use -initWithError: instead

    Initializes an MIKMIDISynthesizer instance which uses the default MIDI instrument audio unit.

    @deprecated This method is deprecated. Use -initWithError: instead.

    On OS X, the default unit is Apple’s DLS Synth audio unit. On iOS, the default is Apple’s AUSampler audio unit.

    Declaration

    Objective-C

    - (nullable instancetype)init;

    Return Value

    An initialized MIKMIDIEndpointSynthesizer or nil if an error occurs.

  • Deprecated

    Use -initWithAudioUnitDescription:error: instead

    Initializes an MIKMIDISynthesizer instance which uses an audio unit matching the provided description.

    @deprecated This method is deprecated. Use -initWithAudioUnitDescription:error: instead.

    Declaration

    Objective-C

    - (nullable instancetype)initWithAudioUnitDescription:
    (AudioComponentDescription)componentDescription;

    Swift

    convenience init?(audioUnitDescription componentDescription: AudioComponentDescription)

    Parameters

    componentDescription

    AudioComponentDescription describing the Audio Unit instrument you would like the synthesizer to use.

    Return Value

    An initialized MIKMIDIEndpointSynthesizer or nil if an error occurs.

  • Deprecated

    Use -selectInstrument:error: instead

    Changes the instrument/voice used by the synthesizer.

    @deprecated This method is deprecated. Use -selectInstrument:error: instead.

    See

    +[MIKMIDISynthesizerInstrument availableInstruments]

    Declaration

    Objective-C

    - (BOOL)selectInstrument:(nonnull MIKMIDISynthesizerInstrument *)instrument;

    Swift

    func selectInstrument(_ instrument: MIKMIDISynthesizerInstrument) -> Bool

    Parameters

    instrument

    An MIKMIDISynthesizerInstrument instance.

    Return Value

    YES if the instrument was successfully changed, NO if the change failed.

  • Deprecated

    Use -setupAUGraphWithError: instead

    Sets up the AUGraph for the instrument. Do not call this method, as it is called automatically during initialization.

    The method is provided to give subclasses a chance to override the AUGraph behavior for the instrument. If you do override it, you will need to create an AudioUnit instrument and set it to the instrument property. Also, if you intend to use the graph property, you will be responsible for setting that as well. DisposeAUGraph() is called on the previous graph when setting the graph property, and in dealloc.

    @deprecated This method is deprecated. Use -setupAUGraphWithError: instead.

    Declaration

    Objective-C

    - (BOOL)setupAUGraph;

    Swift

    func setupAUGraph() -> Bool

    Return Value

    YES is setting up the graph was succesful, and initialization should continue, NO if setting up the graph failed and initialization should return nil.

  • Deprecated

    Use instrumentUnit instead

    @deprecated This has been (renamed to) instrumentUnit. Use that instead.

    Declaration

    Objective-C

    @property (nonatomic) DEPRECATED_MSG_ATTRIBUTE("Use instrumentUnit instead") AudioUnit instrument;

    Swift

    var instrument: AudioUnit { get set }