AVAssetReader Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/AVFoundation.framework
Availability
Available in iOS 4.1 and later.
Declared in
AVAssetReader.h

Overview

You use an AVAssetReader object to obtain media data of an asset, whether the asset is file-based or represents an assemblage of media data from multiple sources (as with an AVComposition object).

AVAssetReader lets you:

AVAssetReader’s pipelines are multithreaded internally. After you initiate reading with initWithAsset:error:, a reader loads and processes a reasonable amount of sample data ahead of use so that retrieval operations such as copyNextSampleBuffer (AVAssetReaderOutput) can have very low latency.

Tasks

Creating a Reader

Managing Outputs

Controlling Reading

Asset Properties

Properties

asset

The asset with which the receiver was initialized. (read-only)

@property(nonatomic, retain, readonly) AVAsset *asset
Discussion

Concrete instances of AVAssetReader with specific AVAssetTrack instances must obtain those tracks from the asset returned by this property.

Availability
  • Available in iOS 4.1 and later.
Declared In
AVAssetReader.h

error

Describes the error that occurred if the status is AVAssetReaderStatusFailed. (read-only)

@property(nonatomic, readonly) NSError *error
Discussion

This property is thread safe.

The value of this property describes what caused the reader to no longer be able to read its asset. If the reader’s status is not AVAssetReaderStatusFailed, the value of this property is nil.

Availability
  • Available in iOS 4.1 and later.
Declared In
AVAssetReader.h

outputs

The outputs from which clients of reader can read media data. (read-only)

@property(nonatomic, readonly) NSArray *outputs
Discussion

The array contains concrete instances of AVAssetReaderOutput associated with the reader.

Availability
  • Available in iOS 4.1 and later.
Declared In
AVAssetReader.h

status

The status of the reading of sample buffers from the asset. (read-only)

@property(nonatomic, readonly) AVAssetReaderStatus status
Discussion

This property is thread safe. For possible values, see “AVAssetReaderStatus.”

The value of this property indicates whether reading is in progress, has completed successfully, has been canceled, or has failed. You should check the value of this property after the AVAssetReaderOutput method copyNextSampleBuffer returns NULL to determine why no more samples could be read.

Availability
  • Available in iOS 4.1 and later.
Declared In
AVAssetReader.h

timeRange

The time range of the asset that should be read.

@property(nonatomic) CMTimeRange timeRange
Discussion

The intersection of the value of this property and CMTimeRangeMake(kCMTimeZero, asset.duration) determines the time range of the asset from which media data will be read.

The default value is CMTimeRangeMake(kCMTimeZero, kCMTimePositiveInfinity).

You cannot change the value of this property after reading has started.

Availability
  • Available in iOS 4.1 and later.
Declared In
AVAssetReader.h

Class Methods

assetReaderWithAsset:error:

Returns an asset reader for reading media data from a specified asset.

+ (AVAssetReader *)assetReaderWithAsset:(AVAsset *)asset error:(NSError **)outError
Parameters
asset

The asset from which media data is to be read.

outError

If initialization of the reader fails, upon return contains an error that describes the problem.

Return Value

An asset reader, initialized for reading media data from asset.

Availability
  • Available in iOS 4.1 and later.
Declared In
AVAssetReader.h

Instance Methods

addOutput:

Adds a given output to the receiver.

- (void)addOutput:(AVAssetReaderOutput *)output
Parameters
output

The reader output to add.

Discussion

Outputs are created with a reference to one or more AVAssetTrack objects. Adding an output to an asset reader indicates to the reader that it should source from those tracks. The tracks must be owned by the asset returned by the reader’s asset property.

You cannot add an output after reading has started.

Availability
  • Available in iOS 4.1 and later.
Declared In
AVAssetReader.h

canAddOutput:

Returns a Boolean value that indicates whether a given output can be added to the receiver.

- (BOOL)canAddOutput:(AVAssetReaderOutput *)output
Parameters
output

The reader output to be tested.

Return Value

YES if output can be added to the receiver, otherwise NO.

Discussion

You cannot add an output that reads from a track of an asset other than the asset used to initialize the receiver.

Availability
  • Available in iOS 4.1 and later.
Declared In
AVAssetReader.h

cancelReading

Cancels any background work and prevents the receiver’s outputs from reading more samples.

- (void)cancelReading
Discussion

If you want to stop reading samples from the receiver before reaching the end of its time range, you should call this method to stop any background read ahead operations that the may have been in progress.

Availability
  • Available in iOS 4.1 and later.
Declared In
AVAssetReader.h

initWithAsset:error:

Initializes an asset reader for reading media data from a specified asset.

- (id)initWithAsset:(AVAsset *)asset error:(NSError **)outError
Parameters
asset

The asset from which media data is to be read.

outError

If initialization of the reader fails, upon return contains an error that describes the problem.

Return Value

An asset reader, initialized for reading media data from asset.

Availability
  • Available in iOS 4.1 and later.
Declared In
AVAssetReader.h

startReading

Prepares the receiver for obtaining sample buffers from the asset.

- (BOOL)startReading
Return Value

YES if the reader is able to start reading, otherwise NO.

Discussion

This method validates the entire collection of settings for outputs for tracks, for audio mixdown, and for video composition and initiates reading of all outputs.

status signals the terminal state of the asset reader, and if a failure occurs, error describes the failure.

Availability
  • Available in iOS 4.1 and later.
Declared In
AVAssetReader.h

Constants

AVAssetReaderStatus

Constants that indicate the reader’s status.

enum {
   AVAssetReaderStatusUnknown = 0,
   AVAssetReaderStatusReading,
   AVAssetReaderStatusCompleted,
   AVAssetReaderStatusFailed,
   AVAssetReaderStatusCancelled,
};
typedef NSInteger AVAssetReaderStatus;
Constants
AVAssetReaderStatusUnknown

Indicates that startReading has not yet been invoked.

Available in iOS 4.1 and later.

Declared in AVAssetReader.h.

AVAssetReaderStatusReading

Indicates that the reader is ready to provide more sample buffers to its outputs.

Available in iOS 4.1 and later.

Declared in AVAssetReader.h.

AVAssetReaderStatusCompleted

Indicates that the reader has provided all available sample buffers to all of its outputs.

Available in iOS 4.1 and later.

Declared in AVAssetReader.h.

AVAssetReaderStatusFailed

Indicates that reading failed.

Available in iOS 4.1 and later.

Declared in AVAssetReader.h.

AVAssetReaderStatusCancelled

Indicates that reading was cancelled using cancelReading.

Available in iOS 4.1 and later.

Declared in AVAssetReader.h.

Discussion

You access the reader’s status using the status property.