/** @method init
    @abstract
        Initialize a new engine.
    @discussion
        On creation, the engine is by default connected to an audio device and automatically renders
        in realtime. It can be configured to operate in manual rendering mode through
        `enableManualRenderingMode:format:maximumFrameCount:error:`.
*/
public init()

/**    @method attachNode:
    @abstract
        Take ownership of a new node.
    @param node
        The node to be attached to the engine.
    @discussion
        To support the instantiation of arbitrary AVAudioNode subclasses, instances are created
        externally to the engine, but are not usable until they are attached to the engine via
        this method. Thus the idiom, without ARC, is:

<pre>
// when building engine:
AVAudioNode *_player;    // member of controller class (for example)
...
_player = [[AVAudioPlayerNode alloc] init];
[engine attachNode: _player];
...
// when destroying engine (without ARC)
[_player release];
</pre>
*/
open func attach(_ node: AVAudioNode)

/**    @method detachNode:
    @abstract
        Detach a node previously attached to the engine.
    @discussion
        If necessary, the engine will safely disconnect the node before detaching it.
*/
open func detach(_ node: AVAudioNode)

/** @method connect:to:fromBus:toBus:format:
    @abstract
        Establish a connection between two nodes.
    @param node1
        The source node
    @param node2
        The destination node
    @param bus1
        The output bus on the source node
    @param bus2
        The input bus on the destination node
    @param format
        If non-nil, the format of the source node's output bus is set to this
        format. In all cases, the format of the destination node's input bus is set to
        match that of the source node's output bus.
    @discussion
        Nodes have input and output buses (AVAudioNodeBus). Use this method to establish
        one-to-one connections betweeen nodes. Connections made using this method are always
        one-to-one, never one-to-many or many-to-one.

        Note that any pre-existing connection(s) involving the source's output bus or the
        destination's input bus will be broken.
*/
open func connect(_ node1: AVAudioNode, to node2: AVAudioNode, fromBus bus1: AVAudioNodeBus, toBus bus2: AVAudioNodeBus, format: AVAudioFormat?)

/**    @method connect:to:format:
    @abstract
        Establish a connection between two nodes
    @discussion
        This calls connect:to:fromBus:toBus:format: using bus 0 on the source node,
        and bus 0 on the destination node, except in the case of a destination which is a mixer,
        in which case the destination is the mixer's nextAvailableInputBus.
*/
open func connect(_ node1: AVAudioNode, to node2: AVAudioNode, format: AVAudioFormat?)

/** @method connect:toConnectionPoints:fromBus:format:
    @abstract
        Establish connections between a source node and multiple destination nodes.
    @param sourceNode
        The source node
    @param destNodes
        An array of AVAudioConnectionPoint objects specifying destination
        nodes and busses
    @param sourceBus
        The output bus on source node
    @param format
        If non-nil, the format of the source node's output bus is set to this
        format. In all cases, the format of the destination nodes' input bus is set to
        match that of the source node's output bus
    @discussion
        Use this method to establish connections from a source node to multiple destination nodes.
        Connections made using this method are either one-to-one (when a single destination
        connection is specified) or one-to-many (when multiple connections are specified), but
        never many-to-one.

        To incrementally add a new connection to a source node, use this method with an array
        of AVAudioConnectionPoint objects comprising of pre-existing connections (obtained from
        `outputConnectionPointsForNode:outputBus:`) and the new connection.

        Note that any pre-existing connection involving the destination's input bus will be
        broken. And, any pre-existing connection on source node which is not a part of the
        specified destination connection array will also be broken.

        Also note that when the output of a node is split into multiple paths, all the paths
        must render at the same rate until they reach a common mixer.
        In other words, starting from the split node until the common mixer node where all split
        paths terminate, you cannot have:
            - any AVAudioUnitTimeEffect
            - any sample rate conversion
*/
@available(OSX 10.11, *)
open func connect(_ sourceNode: AVAudioNode, to destNodes: [AVAudioConnectionPoint], fromBus sourceBus: AVAudioNodeBus, format: AVAudioFormat?)

/** @method disconnectNodeInput:bus:
    @abstract
        Remove a connection between two nodes.
    @param node
        The node whose input is to be disconnected
    @param bus
        The destination's input bus to disconnect
*/
open func disconnectNodeInput(_ node: AVAudioNode, bus: AVAudioNodeBus)

/**    @method disconnectNodeInput:
    @abstract
        Remove a connection between two nodes.
    @param node
        The node whose inputs are to be disconnected
    @discussion
        Connections are broken on each of the node's input busses.
*/
open func disconnectNodeInput(_ node: AVAudioNode)

/** @method disconnectNodeOutput:bus:
    @abstract
        Remove a connection between two nodes.
    @param node
        The node whose output is to be disconnected
    @param bus
        The source's output bus to disconnect
*/
open func disconnectNodeOutput(_ node: AVAudioNode, bus: AVAudioNodeBus)

/**    @method disconnectNodeOutput:
    @abstract
        Remove a connection between two nodes.
    @param node
        The node whose outputs are to be disconnected
    @discussion
        Connections are broken on each of the node's output busses.
*/
open func disconnectNodeOutput(_ node: AVAudioNode)

/**    @method prepare
    @abstract
        Prepare the engine for starting.
    @discussion
        This method preallocates many of the resources the engine requires in order to start.
        It can be used to be able to start more responsively.
*/
open func prepare()

/** @method startAndReturnError:
    @abstract
        Start the engine.
    @return
        YES for success
    @discussion
        Calls prepare if it has not already been called since stop.

        When the engine is rendering to/from an audio device, starts the audio hardware via the
        AVAudioInputNode and/or AVAudioOutputNode instances in the engine. Audio begins to flow
        through the engine.
        Reasons for potential failure to start in this mode include:
        1. There is problem in the structure of the graph. Input can't be routed to output or to a
            recording tap through converter type nodes.
        2. An AVAudioSession error.
        3. The driver failed to start the hardware.

        In manual rendering mode, prepares the engine to render when requested by the client.
*/
open func start() throws

/**    @method pause
    @abstract
        Pause the engine.
    @discussion
        When the engine is rendering to/from an audio device, stops the audio hardware and the flow
        of audio through the engine. When operating in this mode, it is recommended that the engine
        be paused or stopped (as applicable) when not in use, to minimize power consumption.

        Pausing the engine does not deallocate the resources allocated by prepare. Resume the
        engine by invoking start again.
*/
open func pause()

/**    @method reset
    @abstract reset
        Reset all of the nodes in the engine.
    @discussion
        This will reset all of the nodes in the engine. This is useful, for example, for silencing
        reverb and delay tails.

        In manual rendering mode, the render timeline is reset to a sample time of zero.
*/
open func reset()

/** @method stop
    @abstract
        When the engine is rendering to/from an audio device, stops the audio hardware and the
        engine. When operating in this mode, it is recommended that the engine be paused or stopped
         (as applicable) when not in use, to minimize power consumption.

        Stopping the engine releases the resources allocated by prepare.
*/
open func stop()

/** @method inputConnectionPointForNode:inputBus:
    @abstract
        Get connection information on a node's input bus.
    @param node
        The node whose input connection is being queried.
    @param bus
        The node's input bus on which the connection is being queried.
    @return
        An AVAudioConnectionPoint object with connection information on the node's
        specified input bus.
    @discussion
        Connections are always one-to-one or one-to-many, never many-to-one.

        Returns nil if there is no connection on the node's specified input bus.
*/
@available(OSX 10.11, *)
open func inputConnectionPoint(for node: AVAudioNode, inputBus bus: AVAudioNodeBus) -> AVAudioConnectionPoint?

/** @method outputConnectionPointsForNode:outputBus:
    @abstract
        Get connection information on a node's output bus.
    @param node
        The node whose output connections are being queried.
    @param bus
        The node's output bus on which connections are being queried.
    @return
        An array of AVAudioConnectionPoint objects with connection information on the node's
        specified output bus.
    @discussion
        Connections are always one-to-one or one-to-many, never many-to-one.

        Returns an empty array if there are no connections on the node's specified output bus.
*/
@available(OSX 10.11, *)
open func outputConnectionPoints(for node: AVAudioNode, outputBus bus: AVAudioNodeBus) -> [AVAudioConnectionPoint]

/** @property musicSequence
    @abstract
        The MusicSequence previously attached to the engine (if any).
 */
open var musicSequence: MusicSequence?

/** @property outputNode
    @abstract
        The engine's singleton output node.
    @discussion
        Audio output is performed via an output node. The engine creates a singleton on demand when
        this property is first accessed. Connect another node to the input of the output node, or
        obtain a mixer that is connected there by default, using the "mainMixerNode" property.

        When the engine is rendering to/from an audio device, the AVAudioSesssion category and/or
        availability of hardware determine whether an app can perform output. Check the output
        format of output node (i.e. hardware format) for non-zero sample rate and channel count to
        see if output is enabled.
        Trying to perform output through the output node when it is not enabled or available will
        cause the engine to throw an error (when possible) or an exception.

        In manual rendering mode, the output format of the output node will determine the
        render format of the engine. It can be changed through
        `enableManualRenderingMode:format:maximumFrameCount:error:`.
*/
open var outputNode: AVAudioOutputNode { get }

/** @property inputNode
    @abstract
        The engine's singleton input node.
    @discussion
        Audio input is performed via an input node. The engine creates a singleton on demand when
        this property is first accessed. To receive input, connect another node from the output of
        the input node, or create a recording tap on it.

        When the engine is rendering to/from an audio device, the AVAudioSesssion category and/or
        availability of hardware determine whether an app can perform input (e.g. input hardware is
        not available on tvos). Check for the input node's input format (i.e. hardware format) for
        non-zero sample rate and channel count to see if input is enabled.
        Trying to perform input through the input node when it is not enabled or available will
        cause the engine to throw an error (when possible) or an exception.

        In manual rendering mode, the input node can be used to synchronously supply data to
        the engine while it is rendering (see
        `AVAudioInputNode(setManualRenderingInputPCMFormat:inputBlock:)`.
*/
@available(OSX 10.10, *)
open var inputNode: AVAudioInputNode { get }

/** @property mainMixerNode
    @abstract
        The engine's optional singleton main mixer node.
    @discussion
        The engine will construct a singleton main mixer and connect it to the outputNode on demand,
        when this property is first accessed. You can then connect additional nodes to the mixer.

        By default, the mixer's output format (sample rate and channel count) will track the format
        of the output node. You may however make the connection explicitly with a different format.
*/
open var mainMixerNode: AVAudioMixerNode { get }

/** @property running
    @abstract
        The engine's running state.
*/
open var isRunning: Bool { get }

/** @property autoShutdownEnabled
    @abstract
        When auto shutdown is enabled, the engine can start and stop the audio hardware dynamically,
        to conserve power. This is the enforced behavior on watchOS and can be optionally enabled on
        other platforms.
    @discussion
        To conserve power, it is advised that the client pause/stop the engine when not in use.
        But when auto shutdown is enabled, the engine will stop the audio hardware if it was running
        idle for a certain duration, and restart it later when required.
        Note that, because this operation is dynamic, it may affect the start times of the source
        nodes (e.g. `AVAudioPlayerNode`), if the engine has to resume from its shutdown state.

        On watchOS, auto shutdown is always enabled. On other platforms, it is disabled by
        default, but the client can enable it if needed.

        This property is applicable only when the engine is rendering to/from an audio device. If
        the value is changed when the engine is in manual rendering mode, it will take effect
        whenever the engine is switched to render to/from the audio device.
*/
@available(OSX 10.13, *)
open var isAutoShutdownEnabled: Bool

/** @property attachedNodes
    @abstract
        Set of all nodes attached to the engine.
 */
@available(OSX 10.15, *)
open var attachedNodes: Set<AVAudioNode> { get }

/**    @method enableManualRenderingMode:format:maximumFrameCount:error:
    @abstract
        Set the engine to operate in manual rendering mode with the specified render format and
        maximum frame count.
    @param pcmFormat
        The format of the output PCM audio data from the engine
    @param maximumFrameCount
        The maximum number of PCM sample frames the engine will be asked to produce in any single
        render call
     @param outError
        On exit, if the engine cannot switch to the manual rendering mode, a description of the
        error (see `AVAudioEngineManualRenderingError` for the possible errors)
    @return
        YES for success
    @discussion
        Use this method to configure the engine to render in response to requests from the client.

        The engine must be in a stopped state before calling this method.
        The render format must be a PCM format and match the format of the buffer to which
        the engine is asked to render (see `renderOffline:toBuffer:error:`).

        The input data in manual rendering mode can be supplied through the source nodes, e.g.
        `AVAudioPlayerNode`, `AVAudioInputNode` etc.

         When switching to manual rendering mode, the engine:
        1. Switches the input and output nodes to manual rendering mode. Their input and output
           formats may change.
        2. Removes any taps previously installed on the input and output nodes.
        3. Maintains all the engine connections as is.

        Reasons for potential failure when switching to manual rendering mode include:
        - Engine is not in a stopped state.
*/
@available(OSX 10.13, *)
open func enableManualRenderingMode(_ mode: AVAudioEngineManualRenderingMode, format pcmFormat: AVAudioFormat, maximumFrameCount: AVAudioFrameCount) throws

/**    @method disableManualRenderingMode
    @abstract
        Set the engine to render to/from an audio device.
    @discussion
         When disabling the manual rendering mode, the engine:
        1. Stops and resets itself (see `stop` and `reset`).
        2. Switches the output/input nodes to render to/from an audio device. Their input and
           output formats may change.
        3. Removes any taps previously installed on the input and output nodes.
        4. Maintains all the engine connections as is.

        Calling this method when the engine is already rendering to/from an audio device has no
        effect.
*/
@available(OSX 10.13, *)
open func disableManualRenderingMode()

/**    @method renderOffline:toBuffer:error:
    @abstract
        Render call to the engine operating in the offline manual rendering mode
    @param numberOfFrames
        The number of PCM sample frames to be rendered
    @param buffer
        The PCM buffer to which the engine must render the audio
    @param outError
        On exit, if an error occurs during rendering, a description of the error (see
        `AVAudioEngineManualRenderingError` for the possible errors)
    @return
        One of the status codes from `AVAudioEngineManualRenderingStatus`. Irrespective of the
        returned status code, on exit, the output buffer's frameLength will indicate the number of
        PCM samples rendered by the engine
    @discussion
        The engine must be in the offline manual rendering mode
        (`AVAudioEngineManualRenderingModeOffline`) and started before calling this method.

        The format of the buffer must match the render format set through
        `enableManualRenderingMode:format:maximumFrameCount:error:`. The buffer capacity must be
        greater than or equal to the number of samples asked to render.
        On exit, the buffer's frameLength will indicate the number of PCM samples rendered by the
        engine.

         The engine's timeline in manual rendering mode starts at a sample time of zero, and is in
        terms of the render format's sample rate. Resetting the engine (see `reset`) will reset the
        timeline back to zero.

         When rendering in `AVAudioEngineManualRenderingModeRealtime`, this ObjC render method
        must not be used, an error is returned otherwise. Use the block based render call
        (`manualRenderingBlock`) in that mode instead.
*/
@available(OSX 10.13, *)
open func renderOffline(_ numberOfFrames: AVAudioFrameCount, to buffer: AVAudioPCMBuffer) throws -> AVAudioEngineManualRenderingStatus

/**    @property manualRenderingBlock
    @abstract
        Block to render the engine operating in manual rendering mode
    @discussion
        This block based render call must be used to render the engine when operating in
        `AVAudioEngineManualRenderingModeRealtime`. In this mode, the engine operates under
        realtime constraints and will not make any blocking call (e.g. calling libdispatch, blocking
        on a mutex, allocating memory etc.) while rendering.

        Before invoking the rendering functionality, client must fetch this block and cache the
        result. The block can then be called from a realtime context, without any possibility of
        blocking.

        When rendering in `AVAudioEngineManualRenderingModeOffline`, either this block based render
        call or    `renderOffline:toBuffer:error:` ObjC method can be used.
        All the rules outlined in `renderOffline:toBuffer:error:` are applicable here as well.
*/
@available(OSX 10.13, *)
open var manualRenderingBlock: AVAudioEngineManualRenderingBlock { get }

/** @property isInManualRenderingMode
    @abstract
        Whether or not the engine is operating in manual rendering mode, i.e. not connected
        to an audio device and rendering in response to the requests from the client
*/
@available(OSX 10.13, *)
open var isInManualRenderingMode: Bool { get }

/** @property manualRenderingMode
    @abstract
        The manual rendering mode configured on the engine
    @discussion
        This property is meaningful only when the engine is operating in manual rendering mode,
        i.e. when `isInManualRenderingMode` returns true.
*/
@available(OSX 10.13, *)
open var manualRenderingMode: AVAudioEngineManualRenderingMode { get }

/** @property manualRenderingFormat
    @abstract
        The render format of the engine in manual rendering mode.
    @discussion
        Querying this property when the engine is not in manual rendering mode will return an
        invalid format, with zero sample rate and channel count.
*/
@available(OSX 10.13, *)
open var manualRenderingFormat: AVAudioFormat { get }

/** @property manualRenderingMaximumFrameCount
    @abstract
        The maximum number of PCM sample frames the engine can produce in any single render call in
        the manual rendering mode.
    @discussion
        Querying this property when the engine is not in manual rendering mode will return zero.
*/
@available(OSX 10.13, *)
open var manualRenderingMaximumFrameCount: AVAudioFrameCount { get }

/** @property manualRenderingSampleTime
    @abstract
        Indicates where the engine is on its render timeline in manual rendering mode.
    @discussion
        The timeline in manual rendering mode starts at a sample time of zero, and is in terms
        of the render format's sample rate. Resetting the engine (see `reset`) will reset the
        timeline back to zero.
*/
@available(OSX 10.13, *)
open var manualRenderingSampleTime: AVAudioFramePosition { get }

/** @method connectMIDI:to:format:block:
    @abstract
        Establish a MIDI only connection between two nodes.
    @param sourceNode
        The source node.
    @param destinationNode
        The destination node.
    @param format
        If non-nil, the format of the source node's output bus is set to this format.
        In all cases, the format of the source nodes' output bus has to match with the
        destination nodes' output bus format.
        Although the output bus of the source is not in use, the format needs to be set
        in order to be able to use the sample rate for MIDI event timing calculations.
    @param tapBlock
        If non-nil, this block is called from the source node's `AUMIDIOutputEventBlock`
        on the realtime thread. The host can tap the MIDI data of the source node through
        this block. May be nil.
    @discussion
        Use this method to establish a MIDI only connection between a source node and a
        destination node that has MIDI input capability.

        The source node can only be a AVAudioUnit node of type `kAudioUnitType_MIDIProcessor`.
        The destination node types can be `kAudioUnitType_MusicDevice`,
        `kAudioUnitType_MusicEffect` or `kAudioUnitType_MIDIProcessor`.

        Note that any pre-existing MIDI connection involving the destination will be broken.

        Any client installed block on the source node's audio unit `AUMIDIOutputEventBlock`
        will be overwritten when making the MIDI connection.
 */
@available(OSX 10.14, *)
open func connectMIDI(_ sourceNode: AVAudioNode, to destinationNode: AVAudioNode, format: AVAudioFormat?, block tapBlock: AUMIDIOutputEventBlock? = nil)

/** @method connectMIDI:toNodes:format:block:
    @abstract
        Establish a MIDI only connection between a source node and multiple destination nodes.
    @param sourceNode
        The source node.
    @param destinationNodes
        An array of AVAudioNodes specifying destination nodes.
    @param format
        If non-nil, the format of the source node's output bus is set to this format.
        In all cases, the format of the source nodes' output bus has to match with the
        destination nodes' output bus format.
        Although the output bus of the source is not in use, the format needs to be set
        in order to be able to use the sample rate for MIDI event timing calculations.
    @param tapBlock
        If non-nil, this block is called from the source node's `AUMIDIOutputEventBlock`
        on the realtime thread. The host can tap the MIDI data of the source node through
        this block. May be nil.
    @discussion
        Use this method to establish a MIDI only connection between a source node and
        multiple destination nodes.

        The source node can only be a AVAudioUnit node of type `kAudioUnitType_MIDIProcessor`.
        The destination node types can be `kAudioUnitType_MusicDevice`,
        `kAudioUnitType_MusicEffect` or `kAudioUnitType_MIDIProcessor`.

        MIDI connections made using this method are either one-to-one (when a single
        destination connection is specified) or one-to-many (when multiple connections are
        specified), but never many-to-one.

        Note that any pre-existing connection involving the destination will be broken.

        Any client installed block on the source node's audio unit `AUMIDIOutputEventBlock`
        will be overwritten when making the MIDI connection.
 */
@available(OSX 10.14, *)
open func connectMIDI(_ sourceNode: AVAudioNode, to destinationNodes: [AVAudioNode], format: AVAudioFormat?, block tapBlock: AUMIDIOutputEventBlock? = nil)

/** @method disconnectMIDI:from:
    @abstract
        Remove a MIDI connection between two nodes.
    @param sourceNode
        The node whose MIDI output is to be disconnected.
    @param destinationNode
        The node whose MIDI input is to be disconnected.
    @discussion
        If a tap block is installed on the source node, it will be removed when the last
        connection from the source node is removed.
 */
@available(OSX 10.14, *)
open func disconnectMIDI(_ sourceNode: AVAudioNode, from destinationNode: AVAudioNode)

/** @method disconnectMIDI:fromNodes:
    @abstract
        Remove a MIDI connection between one source node and multiple destination nodes.
    @param sourceNode
        The node whose MIDI output is to be disconnected.
    @param destinationNodes
        An array of AVAudioNodes specifying nodes whose MIDI input is to be disconnected.
    @discussion
        If a tap block is installed on the source node, it will be removed when the last
        connection from the source node is removed.
 */
@available(OSX 10.14, *)
open func disconnectMIDI(_ sourceNode: AVAudioNode, from destinationNodes: [AVAudioNode])

/** @method disconnectMIDIInput:
    @abstract
        Disconnects all input MIDI connections of this node.
    @param node
        The node whose MIDI input is to be disconnected.
*/
@available(OSX 10.14, *)
open func disconnectMIDIInput(_ node: AVAudioNode)

/** @method disconnectMIDIOutput:
    @abstract
        Disconnects all output MIDI connections of this node.
    @param node
        The node whose MIDI outputs are to be disconnected.
*/
@available(OSX 10.14, *)
open func disconnectMIDIOutput(_ node: AVAudioNode)