EZAudioPlot

@interface EZAudioPlot : EZPlot

EZAudioPlot, a subclass of EZPlot, is a cross-platform (iOS and OSX) class that plots an audio waveform using Core Graphics.

The caller provides updates a constant stream of updated audio data in the updateBuffer:withBufferSize: function, which in turn will be plotted in one of the plot types:

  • Buffer (EZPlotTypeBuffer) - A plot that only consists of the current buffer and buffer size from the last call to updateBuffer:withBufferSize:. This looks similar to the default openFrameworks input audio example.
  • Rolling (EZPlotTypeRolling) - A plot that consists of a rolling history of values averaged from each buffer. This is the traditional waveform look.

Parent Methods and Properties

See EZPlot for full API methods and properties (colors, plot type, update function)

  • A BOOL that allows optimizing the audio plot’s drawing for real-time displays. Since the update function may be updating the plot’s data very quickly (over 60 frames per second) this property will throttle the drawing calls to be 60 frames per second (or whatever the screen rate is). Specifically, it disables implicit path change animations on the waveformLayer and sets up a display link to render 60 fps (audio updating the plot at 44.1 kHz causes it to re-render 86 fps - far greater than what is needed for a visual display).

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) BOOL shouldOptimizeForRealtimePlot;

    Swift

    var shouldOptimizeForRealtimePlot: Bool { get set }

  • A BOOL indicating whether the plot should center itself vertically.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) BOOL shouldCenterYAxis;

    Swift

    var shouldCenterYAxis: Bool { get set }

  • An EZAudioPlotWaveformLayer that is used to render the actual waveform. By switching the drawing code to Core Animation layers in version 0.2.0 most work, specifically the compositing step, is now done on the GPU. Hence, multiple EZAudioPlot instances can be used simultaneously with very low CPU overhead so these are now practical for table and collection views.

    Declaration

    Objective-C

    @property (readwrite, strong, nonatomic) EZAudioPlotWaveformLayer *waveformLayer;

    Swift

    var waveformLayer: EZAudioPlotWaveformLayer! { get set }

Adjusting The Resolution

  • Sets the length of the rolling history buffer (i.e. the number of points in the rolling plot’s buffer). Can grow or shrink the display up to the maximum size specified by the maximumRollingHistoryLength method. Will return the actual set value, which will be either the given value if smaller than the maximumRollingHistoryLength or maximumRollingHistoryLength if a larger value is attempted to be set. - parameter: historyLength The new length of the rolling history buffer. - returns: The new value equal to the historyLength or the maximumRollingHistoryLength.

    Declaration

    Objective-C

    - (int)setRollingHistoryLength:(int)historyLength;

    Swift

    func setRollingHistoryLength(_ historyLength: Int32) -> Int32

    Parameters

    historyLength

    The new length of the rolling history buffer.

    Return Value

    The new value equal to the historyLength or the maximumRollingHistoryLength.

  • Provides the length of the rolling history buffer (i.e. the number of points in the rolling plot’s buffer). * - returns: An int representing the length of the rolling history buffer

    Declaration

    Objective-C

    - (int)rollingHistoryLength;

    Swift

    func rollingHistoryLength() -> Int32

    Return Value

    An int representing the length of the rolling history buffer

Subclass Methods

  • Main method that handles converting the points created from the updatedBuffer:withBufferSize: method into a CGPathRef to store in the waveformLayer. In this method you can create any path you’d like using the point array (for instance, maybe mapping the points to a circle instead of the standard 2D plane). - parameter: points An array of CGPoint structures, with the x values ranging from 0 - (pointCount - 1) and y values containing the last audio data’s buffer. - parameter: pointCount A UInt32 of the length of the point array. - parameter: rect An EZRect (CGRect on iOS or NSRect on OSX) that the path should be created relative to. - returns: A CGPathRef that is the path you’d like to store on the waveformLayer to visualize the audio data.

    Declaration

    Objective-C

    - (CGPathRef)createPathWithPoints:(CGPoint *)points
                       pointCount:(UInt32)pointCount
                           inRect:(EZRect)rect;

    Swift

    func createPath(withPoints points: UnsafeMutablePointer

    Parameters

    points

    An array of CGPoint structures, with the x values ranging from 0 - (pointCount - 1) and y values containing the last audio data’s buffer.
    pointCount

    A UInt32 of the length of the point array.
    rect

    An EZRect (CGRect on iOS or NSRect on OSX) that the path should be created relative to.

    Return Value

    A CGPathRef that is the path you’d like to store on the waveformLayer to visualize the audio data.

  • Provides the default length of the rolling history buffer when the plot is initialized. Default is EZAudioPlotDefaultHistoryBufferLength constant. - returns: An int describing the initial length of the rolling history buffer.

    Declaration

    Objective-C

    - (int)defaultRollingHistoryLength;

    Swift

    func defaultRollingHistoryLength() -> Int32

    Return Value

    An int describing the initial length of the rolling history buffer.

  • Called after the view has been created. Subclasses should use to add any additional methods needed instead of overriding the init methods.

    Declaration

    Objective-C

    - (void)setupPlot;

    Swift

    func setupPlot()

  • Provides the default number of points that will be used to initialize the graph’s points data structure that holds. Essentially the plot starts off as a flat line of this many points. Default is 100. - returns: An int describing the initial number of points the plot should have when flat lined.

    Declaration

    Objective-C

    - (int)initialPointCount;

    Swift

    func initialPointCount() -> Int32

    Return Value

    An int describing the initial number of points the plot should have when flat lined.

  • Provides the default maximum rolling history length - that is, the maximum amount of points the setRollingHistoryLength: method may be set to. If a length higher than this is set then the plot will likely crash because the appropriate resources are only allocated once during the plot’s initialization step. Defualt is EZAudioPlotDefaultMaxHistoryBufferLength constant. - returns: An int describing the maximum length of the absolute rolling history buffer.

    Declaration

    Objective-C

    - (int)maximumRollingHistoryLength;

    Swift

    func maximumRollingHistoryLength() -> Int32

    Return Value

    An int describing the maximum length of the absolute rolling history buffer.

  • Method to cause the waveform layer’s path to get recreated and redrawn on screen using the last buffer of data provided. This is the equivalent to the drawRect: method used to normally subclass a view’s drawing. This normally don’t need to be overrode though - a better approach would be to override the createPathWithPoints:pointCount:inRect: method.

    Declaration

    Objective-C

    - (void)redraw;

    Swift

    func redraw()

  • Main method used to copy the sample data from the source buffer and update the plot. Subclasses can overwrite this method for custom behavior. - parameter: data A float array of the sample data. Subclasses should copy this data to a separate array to avoid threading issues. - parameter: length The length of the float array as an int.

    Declaration

    Objective-C

    - (void)setSampleData:(float *)data length:(int)length;

    Swift

    func setSampleData(_ data: UnsafeMutablePointer

    Parameters

    data

    A float array of the sample data. Subclasses should copy this data to a separate array to avoid threading issues.
    length

    The length of the float array as an int.

  • Undocumented

    See more

    Declaration

    Objective-C

    @interface EZAudioPlot : EZPlot

  • Undocumented

    See more

    Declaration

    Objective-C

    @interface EZAudioPlot : EZPlot

  • Undocumented

    See more

    Declaration

    Objective-C

    @interface EZAudioPlot : EZPlot

  • Undocumented

    See more

    Declaration

    Objective-C

    @interface EZAudioPlot : EZPlot