AVAssetWriter 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	AVAssetWriter.h
Related sample code	RosyWriter StopNGo for iOS

Overview

You use an AVAssetWriter object to write media data to a new file of a specified audiovisual container type, such as a QuickTime movie file or an MPEG-4 file, with support for automatic interleaving of media data for multiple concurrent tracks.

You can get the media data for one or more assets from instances of AVAssetReader or even from outside the AV Foundation API set. Media data is presented to AVAssetWriter for writing in the form of CMSampleBuffers (see CMSampleBuffer Reference). Sequences of sample data appended to the asset writer inputs are considered to fall within “sample-writing sessions.” You must call startSessionAtSourceTime: to begin one of these sessions.

Using AVAssetWriter, you can optionally re-encode media samples as they are written. You can also optionally write metadata collections to the output file.

You can only use a given instance of AVAssetWriter once to write to a single file. If you want to write to files multiple times, you must use a new instance of AVAssetWriter each time.

Tasks

Creating an Asset Writer

Writing Data

Managing Inputs

Managing Session Time

Configuring Output

Properties

availableMediaTypes

The media types for which inputs can be added (read-only)

@property(nonatomic, readonly) NSArray *availableMediaTypes

Discussion

Some media types may not be accepted within the type of file with which the writer was initialized.

Availability

Available in iOS 4.1 and later.

Declared In

AVAssetWriter.h

error

If the receiver's status is AVAssetWriterStatusFailed, describes the error that caused the failure. (read-only)

@property(readonly) NSError *error

Discussion

The value of this property is an error object that describes what caused the receiver to no longer be able to write to its output file. If the receiver's status is not AVAssetWriterStatusFailed, the value of this property is nil.

Availability

Available in iOS 4.1 and later.

Related Sample Code

Declared In

AVAssetWriter.h

inputs

The asset writer inputs associated with the asset writer. (read-only)

@property(nonatomic, readonly) NSArray *inputs

Discussion

The array contains AVAssetWriterInput objects.

Availability

Available in iOS 4.1 and later.

Declared In

AVAssetWriter.h

metadata

The collection of metadata for association with the asset and for carriage in the output file.

@property(nonatomic, copy) NSArray *metadata

Discussion

The array contains AVMetadataItem objects.

Special Considerations

You cannot set the value after writing has started.

Availability

Available in iOS 4.1 and later.

Declared In

AVAssetWriter.h

movieFragmentInterval

The time to elapse between writing movie fragments.

@property(nonatomic) CMTime movieFragmentInterval

Discussion

This property only applies to the QuickTime movie file type.

Sometimes a write operation may be unexpectedly interrupted (because a process crashes, for example). By using movie fragments, such a partially-written QuickTime movie file can be successfully opened and played up to the largest multiple of movieFragmentInterval smaller than the point at which the write operation was interrupted.

The default value is kCMTimeInvalid, which means that movie fragments should not be used, that only a movie atom describing all of the media in the file should be written.

Special Considerations

You cannot set the value after writing has started.

Availability

Available in iOS 4.1 and later.

Declared In

AVAssetWriter.h

movieTimeScale

Specifies the asset-level time scale to be used.

@property(nonatomic) CMTimeScale movieTimeScale

Discussion

For file types that contain a moov atom, such as QuickTime Movie files, specifies the asset-level time scale to be used.

The default value is 0, which indicates that you should choose a convenient value, if applicable.

Special Considerations

You cannot set the value after writing has started.

Availability

Available in iOS 4.3 and later.

Declared In

AVAssetWriter.h

outputFileType

The file format of the writer’s output. (read-only)

@property(nonatomic, copy, readonly) NSString *outputFileType

Discussion

The format is identified by the UTI, specified when the writer is initialized.

Availability

Available in iOS 4.1 and later.

Declared In

AVAssetWriter.h

outputURL

The URL to which output is directed. (read-only)

@property(nonatomic, copy, readonly) NSURL *outputURL

Discussion

The URL is the same as that specified when the writer is initialized.

Availability

Available in iOS 4.1 and later.

Declared In

AVAssetWriter.h

shouldOptimizeForNetworkUse

Indicates whether the output file should be written in way that makes it more suitable for playback over a network.

@property(nonatomic) BOOL shouldOptimizeForNetworkUse

Discussion

When the value of this property is YES, the output file will be written in such a way that playback can start after only a small amount of the file is downloaded.

The default value is NO.

Special Considerations

You cannot set the value after writing has started.

Availability

Available in iOS 4.1 and later.

Declared In

AVAssetWriter.h

status

The status of writing samples to the receiver's output file. (read-only)

@property(readonly) AVAssetWriterStatus status

Discussion

The value of this property is an AVAssetWriterStatus constant that indicates whether writing is in progress, has completed successfully, has been canceled, or has failed. If an attempt to append samples fails, you can check the value of this property to determine why no more samples could be written.

Availability

Available in iOS 4.1 and later.

Related Sample Code

RosyWriter

Declared In

AVAssetWriter.h

Class Methods

assetWriterWithURL:fileType:error:

Returns an asset writer for writing to the file identified by a given URL in a format specified by a given UTI.

+ (AVAssetWriter *)assetWriterWithURL:(NSURL *)outputURL fileType:(NSString *)outputFileType error:(NSError **)outError

Parameters

outputURL

The location of the file to be written. The URL must be a file URL.

outputFileType

The UTI-identified format of the file to be written.

For example, AVFileTypeQuickTimeMovie for a QuickTime movie file, AVFileTypeMPEG4 for an MPEG-4 file, and AVFileTypeAMR for an adaptive multi-rate audio format file.

outError

If initialization of the asset writer fails, upon return contains an error object that describes the problem.

Return Value

An asset writer for writing to the file identified by URL in the format specified by outputFileType, or nil if the writer could not be initialized.

Discussion

Writing will fail if a file already exists at URL. UTIs for container formats that can be written are declared in AVMediaFormat.h.

Availability

Available in iOS 4.1 and later.

Declared In

AVAssetWriter.h

Instance Methods

addInput:

Adds an input to the receiver.

- (void)addInput:(AVAssetWriterInput *)input

Parameters

input: The asset writer input to be added.

Discussion

Inputs are created with a media type and output settings. These both must be compatible with the receiver.

Special Considerations

You cannot add inputs after writing has started.

Availability

Available in iOS 4.1 and later.

Declared In

AVAssetWriter.h

canAddInput:

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

- (BOOL)canAddInput:(AVAssetWriterInput *)input

Parameters

input: The asset writer input to be tested.

Return Value

YES if input can be added, otherwise NO.

Discussion

You cannot add an input that accepts media data of a type that is not compatible with the receiver, or with output settings that are not compatible with the receiver.

Availability

Available in iOS 4.1 and later.

Declared In

AVAssetWriter.h

canApplyOutputSettings:forMediaType:

Returns a Boolean value that indicates whether give output settings are supported for a specified media type.

- (BOOL)canApplyOutputSettings:(NSDictionary *)outputSettings forMediaType:(NSString *)mediaType

Parameters

outputSettings: The output settings to validate.
mediaType: The media type for which the output settings are validated.

Return Value

YES if the output settings in outputSettings are supported for mediaType, otherwise NO.

Discussion

You can use this method to test, for example, whether video output settings that specify H.264 compression will fail (as would be the case if the container format for which the writer was initialized does not support the carriage of H.264-compressed video).

Availability

Available in iOS 4.1 and later.

Declared In

AVAssetWriter.h

cancelWriting

Instructs the writer to cancel writing.

- (void)cancelWriting

Discussion

This method blocks until writing is canceled.

Availability

Available in iOS 4.1 and later.

Declared In

AVAssetWriter.h

endSessionAtSourceTime:

Concludes an explicit sample-writing session.

- (void)endSessionAtSourceTime:(CMTime)endTime

Parameters

endTime: The ending asset time for the sample-writing session, in the timeline of the source samples.

Discussion

You may invoke this method to complete a session you began by invoking startSessionAtSourceTime:.

You do not need to call this method; if you call finishWriting without calling this method, the session's effective end time will be the latest end timestamp of the session's samples (that is, no samples will be edited out at the end).

The endTime defines the moment on the timeline of source samples at which the session ends. In the case of the QuickTime movie file format, each sample-writing session's startTime…endTime pair corresponds to a period of movie time into which the session's samples are inserted. Samples with later timestamps will be still be added to the media but will be edited out of the movie. So if the first session has duration D1 = endTime - startTime, it will be inserted into the movie at movie time 0 through D1; the second session would be inserted into the movie at movie time D1 through D1+D2, and so on.

It is legal to have a session with no samples; this will cause creation of an empty edit of the prescribed duration.

Availability

Available in iOS 4.1 and later.

Declared In

AVAssetWriter.h

finishWritingWithCompletionHandler:

Marks all unfinished inputs as finished and completes the writing of the output file.

- (void)finishWritingWithCompletionHandler:(void (^)(void))handler

Parameters

handler: The specified handler to be invoked once the writing of the output file is finished or if a failure or cancellation occurs in the meantime.

Discussion

This method returns immediately and causes its work to be performed asynchronously. To determine whether the operation succeeded, you can check the value of the status property within the handler parameter. If the status is AVAssetWriterStatusFailed, then the error property will contain an instance of NSError that describes the failure.

To guarantee that all sample buffers are successfully written, you must ensure that all calls to appendSampleBuffer: and appendPixelBuffer:withPresentationTime: have returned before invoking this method.

Availability

Available in iOS 6.0 and later.

Declared In

AVAssetWriter.h

initWithURL:fileType:error:

Initializes an asset writer for writing to the file identified by a given URL in a format specified by a given UTI.

- (id)initWithURL:(NSURL *)outputURL fileType:(NSString *)outputFileType error:(NSError **)outError

Parameters

outputURL

The location of the file to be written. The URL must be a file URL.

outputFileType

The UTI-identified format of the file to be written.

For example, AVFileTypeQuickTimeMovie for a QuickTime movie file, AVFileTypeMPEG4 for an MPEG-4 file, and AVFileTypeAMR for an adaptive multi-rate audio format file.

outError

If initialization of the asset writer fails, upon return contains an error object that describes the problem.

Return Value

An asset writer for writing to the file identified by URL in the format specified by outputFileType, or nil if the writer could not be initialized.

Discussion

Writing will fail if a file already exists at URL. UTIs for container formats that can be written are declared in AVMediaFormat.h.

Availability

Available in iOS 4.1 and later.

Related Sample Code

Declared In

AVAssetWriter.h

startSessionAtSourceTime:

Initiates a sample-writing session for the output asset.

- (void)startSessionAtSourceTime:(CMTime)startTime

Parameters

startTime: The starting asset time for the sample-writing session, in the timeline of the source samples.

Discussion

Sequences of sample data appended to the asset writer inputs are considered to fall within “sample-writing sessions.” You must call this method to begin one of these sessions.

Each writing session has a start time which, where allowed by the file format being written, defines the mapping from the timeline of source samples onto the file's timeline. In the case of the QuickTime movie file format, the first session begins at movie time 0, so a sample appended with timestamp T will be played at movie time (T-startTime). Samples with timestamps before startTime will still be added to the output media but will be edited out of the movie. If the earliest buffer for an input is later than startTime, an empty edit will be inserted to preserve synchronization between tracks of the output asset.

Special Considerations

It is an error to invoke this method twice in a row without invoking endSessionAtSourceTime:: in between.

Availability

Available in iOS 4.1 and later.

Declared In

AVAssetWriter.h

startWriting

Tells the writer to start writing its output.

- (BOOL)startWriting

Return Value

YES if writing can be started, otherwise NO.

Discussion

You must call this method after all inputs have added and other configuration properties have been set to tell the receiver to prepare for writing. After invoking this method, you can start writing sessions using startSessionAtSourceTime: and can write media samples using the methods provided by each of the writer’s inputs.

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

AVAssetWriter.h

Constants

AVAssetWriterStatus

Type for status constants. See “Status Constants” for possible values.

typedef NSInteger AVAssetWriterStatus;

Availability

Available in iOS 4.1 and later.

Declared In

AVAssetWriter.h

Status Constants

These constants are returned by the status property to indicate whether it can successfully write samples to its output file.

enum {
   AVAssetWriterStatusUnknown = 0,
   AVAssetWriterStatusWriting,
   AVAssetWriterStatusCompleted,
   AVAssetWriterStatusFailed,
   AVAssetWriterStatusCancelled
};