AVAssetWriter Class Reference

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

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

Managing Asset Writer Input Groups

Properties

availableMediaTypes

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

@property(nonatomic, readonly) NSArray *availableMediaTypes
Discussion

An array of values specifed in Media_Types.

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.

This property supports Key-value observing.

Availability
  • Available in iOS 4.1 and later.
Related Sample Code
Declared In
AVAssetWriter.h

inputGroups

An array of asset writer input groups that have been added to the asset writer. (read-only)

@property(nonatomic, readonly) NSArray *inputGroups
Discussion

The value of this property is an NSArray containing concrete instances of AVAssetWriterInputGroup.

Input groups are added to the receiver using the addInputGroup: method.

Availability
  • Available in iOS 7.0 and later.
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

Sometimes a write operation may be unexpectedly interrupted (because a process crashes, for example). By using movie fragments, a partially-written 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 the asset writer will 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

A Boolean value that 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.

This property supports Key-value observing.

Availability
  • Available in iOS 4.1 and later.
Related Sample Code
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. See File_Format_UTIs for values.

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.

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

addInputGroup:

Adds an asset writer input group instance to the asset writer.

- (void)addInputGroup:(AVAssetWriterInputGroup *)inputGroup
Parameters
inputGroup

The asset writer input group to be added.

Discussion

The asset writer will mark the tracks associated with grouped inputs as mutually exclusive to each other for playback or other processing, if the output container format supports mutually exclusive relationships among tracks.

When an input group is added to an asset writer, the value of marksOutputTrackAsEnabled for the AVAssetWriterInput instance set as the default input will automatically be set to YES and all other inputs in the group will be set to NO.

Input groups cannot be added after writing has started.

Availability
  • Available in iOS 7.0 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

canAddInputGroup:

Returns whether an input group can be added to the receiver.

- (BOOL)canAddInputGroup:(AVAssetWriterInputGroup *)inputGroup
Parameters
inputGroup

The asset writer input group to be added.

Return Value

YES if inputGroup can be added to the inputGroups, otherwise NO.

Discussion

If outputFileType specifies a container format that does not support mutually exclusive relationships among tracks, or if the specified instance of AVAssetWriterInputGroup contains inputs with media types that cannot be related, the group cannot be added.

Availability
  • Available in iOS 7.0 and later.
Declared In
AVAssetWriter.h

canApplyOutputSettings:forMediaType:

Returns a Boolean value that indicates whether the specified 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 File Format UTIs.

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.

The status property 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

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
};
typedef NSInteger AVAssetWriterStatus;
Constants
AVAssetWriterStatusUnknown

The current asset writer status is unknown.

Available in iOS 4.1 and later.

Declared in AVAssetWriter.h.

AVAssetWriterStatusWriting

The asset writer is writing.

Available in iOS 4.1 and later.

Declared in AVAssetWriter.h.

AVAssetWriterStatusCompleted

The asset writer has completed writing successfully.

Available in iOS 4.1 and later.

Declared in AVAssetWriter.h.

AVAssetWriterStatusFailed

The asset writer has failed while writing.

Available in iOS 4.1 and later.

Declared in AVAssetWriter.h.

AVAssetWriterStatusCancelled

The asset writer writing has been cancelled.

Available in iOS 4.1 and later.

Declared in AVAssetWriter.h.