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 toupdateBuffer: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 }
-
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 themaximumRollingHistoryLength
ormaximumRollingHistoryLength
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 themaximumRollingHistoryLength
.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
-
Main method that handles converting the points created from the
updatedBuffer:withBufferSize:
method into a CGPathRef to store in thewaveformLayer
. 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 thewaveformLayer
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 isEZAudioPlotDefaultMaxHistoryBufferLength
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 moreDeclaration
Objective-C
@interface EZAudioPlot : EZPlot
-
Undocumented
See moreDeclaration
Objective-C
@interface EZAudioPlot : EZPlot
-
Undocumented
See moreDeclaration
Objective-C
@interface EZAudioPlot : EZPlot
-
Undocumented
See moreDeclaration
Objective-C
@interface EZAudioPlot : EZPlot