AVAssetReader Class Reference

Inherits from	NSObject
Conforms to	NSObject (NSObject)
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:

Read raw un-decoded media samples directly from storage, obtain samples decoded into renderable forms.
Mix multiple audio tracks of the asset and compose multiple video tracks (by using AVAssetReaderAudioMixOutput and AVAssetReaderVideoCompositionOutput).

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. Note, however, that AVAssetReader is not intended for use with real-time sources, and its performance is not guaranteed for real-time operations.

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 “Reader Status Constants.”

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 copyNextSampleBuffer (AVAssetReaderOutput) 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

A type for constants to indicate the reader’s status.

typedef NSInteger AVAssetReaderStatus;

Discussion

For possible values, see “Reader Status Constants.”

Availability

Available in iOS 4.1 and later.

Declared In

AVAssetReader.h

Reader Status Constants

Constants that indicate the reader’s status.

enum {
   AVAssetReaderStatusUnknown = 0,
   AVAssetReaderStatusReading,
   AVAssetReaderStatusCompleted,
   AVAssetReaderStatusFailed,
   AVAssetReaderStatusCancelled,
};