iOS Developer Library

Developer

AVFoundation Framework Reference AVAssetWriter Class Reference

Options
Deployment Target:

On This Page
Language:

AVAssetWriter

Inherits From


Conforms To


Import Statement


Swift

import AVFoundation

Objective-C

@import AVFoundation;

Availability


Available in iOS 4.1 and later

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.

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

    Declaration

    Objective-C

    + (instancetype)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.

    Import Statement

    Objective-C

    @import AVFoundation;

    Availability

    Available in iOS 4.1 and later

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

    Declaration

    Swift

    init!(URL outputURL: NSURL!, fileType outputFileType: String!, error outError: NSErrorPointer)

    Objective-C

    - (instancetype)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.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.1 and later

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

    Declaration

    Swift

    var availableMediaTypes: [AnyObject]! { get }

    Objective-C

    @property(nonatomic, readonly) NSArray *availableMediaTypes

    Discussion

    An array of values specified in Media_Types.

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

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.1 and later

  • Tells the writer to start writing its output.

    Declaration

    Swift

    func startWriting() -> Bool

    Objective-C

    - (BOOL)startWriting

    Return Value

    YEStrue if writing can be started, otherwise NOfalse.

    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.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.1 and later

  • Completes the writing of the output file.

    Declaration

    Objective-C

    - (BOOL)finishWriting

    Return Value

    YEStrue if writing can be finished, otherwise NOfalse.

    Discussion

    This method blocks until writing is finished. When this method returns successfully, the file being written by the receiver is complete and ready to use. You can check the values of the status and error properties for more information on why writing could not be finished.

    Import Statement

    Objective-C

    @import AVFoundation;

    Availability

    Available in iOS 4.1 and later

    Deprecated in iOS 6.0

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

    Declaration

    Swift

    func finishWritingWithCompletionHandler(_ handler: (() -> Void)!)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 6.0 and later

  • Instructs the writer to cancel writing.

    Declaration

    Swift

    func cancelWriting()

    Objective-C

    - (void)cancelWriting

    Discussion

    This method blocks until writing is canceled.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.1 and later

  • outputURL outputURL Property

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

    Declaration

    Swift

    @NSCopying var outputURL: NSURL! { get }

    Objective-C

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

    Discussion

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

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.1 and later

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

    Declaration

    Swift

    var outputFileType: String! { get }

    Objective-C

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

    Discussion

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

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.1 and later

  • error error Property

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

    Declaration

    Swift

    var error: NSError! { get }

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.1 and later

  • status status Property

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

    Declaration

    Swift

    var status: AVAssetWriterStatus { get }

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.1 and later

  • Specifies a directory that is suitable for containing temporary files generated during the export process.

    Declaration

    Swift

    @NSCopying var directoryForTemporaryFiles: NSURL!

    Objective-C

    @property(nonatomic, copy) NSURL *directoryForTemporaryFiles

    Discussion

    An asset writer may need to write temporary files, for example when canPerformMultiplePassesOverSourceMediaData is set to YEStrue. This property specifies where in the filesystem those temporary files are created. All temporary files will be deleted when the asset writing is completed, is canceled, or fails.

    When the value of this property is nil, the asset writer will choose a suitable location when writing temporary files. The default value is nil.

    This property cannot be set after the asset writing has started. The export will fail if the URL points to a location that is not a directory, does not exist, is not on the local file system, or if a file cannot be created in this directory (for example, due to insufficient permissions or sandboxing restrictions).

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 8.0 and later

  • inputs inputs Property

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

    Declaration

    Swift

    var inputs: [AnyObject]! { get }

    Objective-C

    @property(nonatomic, readonly) NSArray *inputs

    Discussion

    The array contains AVAssetWriterInput objects.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.1 and later

    See Also

    – addInput:

  • Adds an input to the receiver.

    Declaration

    Swift

    func addInput(_ input: AVAssetWriterInput!)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.1 and later

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

    Declaration

    Swift

    func canAddInput(_ input: AVAssetWriterInput!) -> Bool

    Objective-C

    - (BOOL)canAddInput:(AVAssetWriterInput *)input

    Parameters

    input

    The asset writer input to be tested.

    Return Value

    YEStrue if input can be added, otherwise NOfalse.

    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.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.1 and later

  • Initiates a sample-writing session for the output asset.

    Declaration

    Swift

    func startSessionAtSourceTime(_ startTime: CMTime)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.1 and later

  • Concludes an explicit sample-writing session.

    Declaration

    Swift

    func endSessionAtSourceTime(_ endTime: CMTime)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.1 and later

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

    Declaration

    Swift

    func canApplyOutputSettings(_ outputSettings: [NSObject : AnyObject]!, forMediaType mediaType: String!) -> Bool

    Objective-C

    - (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

    YEStrue if the output settings in outputSettings are supported for mediaType, otherwise NOfalse.

    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).

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.1 and later

  • metadata metadata Property

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

    Declaration

    Swift

    var metadata: [AnyObject]!

    Objective-C

    @property(nonatomic, copy) NSArray *metadata

    Discussion

    The array contains AVMetadataItem objects.

    Special Considerations

    You cannot set the value after writing has started.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.1 and later

  • The time to elapse between writing movie fragments.

    Declaration

    Swift

    var movieFragmentInterval: CMTime

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.1 and later

  • Specifies the asset-level time scale to be used.

    Declaration

    Swift

    var movieTimeScale: CMTimeScale

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.3 and later

  • A Boolean value that indicates whether the output file should be written in way that makes it more suitable for playback over a network.

    Declaration

    Swift

    var shouldOptimizeForNetworkUse: Bool

    Objective-C

    @property(nonatomic) BOOL shouldOptimizeForNetworkUse

    Discussion

    When the value of this property is YEStrue, 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 NOfalse.

    Special Considerations

    You cannot set the value after writing has started.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.1 and later

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

    Declaration

    Swift

    func addInputGroup(_ inputGroup: AVAssetWriterInputGroup!)

    Objective-C

    - (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 YEStrue and all other inputs in the group will be set to NOfalse.

    Input groups cannot be added after writing has started.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 7.0 and later

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

    Declaration

    Swift

    func canAddInputGroup(_ inputGroup: AVAssetWriterInputGroup!) -> Bool

    Objective-C

    - (BOOL)canAddInputGroup:(AVAssetWriterInputGroup *)inputGroup

    Parameters

    inputGroup

    The asset writer input group to be added.

    Return Value

    YEStrue if inputGroup can be added to the inputGroups, otherwise NOfalse.

    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.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 7.0 and later

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

    Declaration

    Swift

    var inputGroups: [AnyObject]! { get }

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 7.0 and later

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

    Declaration

    Swift

    enum AVAssetWriterStatus : Int { case Unknown case Writing case Completed case Failed case Cancelled }

    Objective-C

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

    Constants

    • Unknown

      AVAssetWriterStatusUnknown

      The current asset writer status is unknown.

      Available in iOS 4.1 and later

    • Writing

      AVAssetWriterStatusWriting

      The asset writer is writing.

      Available in iOS 4.1 and later

    • Completed

      AVAssetWriterStatusCompleted

      The asset writer has completed writing successfully.

      Available in iOS 4.1 and later

    • Failed

      AVAssetWriterStatusFailed

      The asset writer has failed while writing.

      Available in iOS 4.1 and later

    • Cancelled

      AVAssetWriterStatusCancelled

      The asset writer writing has been cancelled.

      Available in iOS 4.1 and later

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.1 and later