Struct AVAssetExportSession

#[repr(C)]
pub struct AVAssetExportSession { /* private fields */ }

Available on crate feature AVAssetExportSession only.

An AVAssetExportSession creates a new timed media resource from the contents of an existing AVAsset in the form described by a specified export preset.

Prior to initializing an instance of AVAssetExportSession, you can invoke +allExportPresets to obtain the complete list of presets available. Use +exportPresetsCompatibleWithAsset: to obtain a list of presets that are compatible with a specific AVAsset.

To configure an export, initialize an AVAssetExportSession with an AVAsset that contains the source media, an AVAssetExportPreset, the output file type, (a UTI string from those defined in AVMediaFormat.h) and the output URL.

After configuration is complete, invoke exportAsynchronouslyWithCompletionHandler: to start the export process. This method returns immediately; the export is performed asynchronously. Invoke the -progress method to check on the progress. Note that in some cases, depending on the capabilities of the device, when multiple exports are attempted at the same time some may be queued until others have been completed. When this happens, the status of a queued export will indicate that it’s “waiting”.

Whether the export fails, completes, or is cancelled, the completion handler you supply to -exportAsynchronouslyWithCompletionHandler: will be called. Upon completion, the status property indicates whether the export has completed successfully. If it has failed, the value of the error property supplies additional information about the reason for the failure.

See also Apple’s documentation

Implementations

impl AVAssetExportSession

pub unsafe fn init(this: Allocated<Self>) -> Retained<Self>

pub unsafe fn new() -> Retained<Self>

pub unsafe fn exportSessionWithAsset_presetName( asset: &AVAsset, preset_name: &NSString, ) -> Option<Retained<Self>>

Available on crate feature AVAsset only.

Returns an instance of AVAssetExportSession for the specified source asset and preset.

Parameter asset: An AVAsset object that is intended to be exported.

Parameter presetName: An NSString specifying the name of the preset template for the export.

Returns: An instance of AVAssetExportSession.

If the specified asset belongs to a mutable subclass of AVAsset, AVMutableComposition or AVMutableMovie, the results of any export-related operation are undefined if you mutate the asset after the operation commences. These operations include but are not limited to: 1) testing the compatibility of export presets with the asset, 2) calculating the maximum duration or estimated length of the output file, and 3) the export operation itself.

pub unsafe fn initWithAsset_presetName( this: Allocated<Self>, asset: &AVAsset, preset_name: &NSString, ) -> Option<Retained<Self>>

Available on crate feature AVAsset only.

Initialize an AVAssetExportSession with the specified preset and set the source to the contents of the asset.

Parameter asset: An AVAsset object that is intended to be exported.

Parameter presetName: An NSString specifying the name of the preset template for the export.

Returns: Returns the initialized AVAssetExportSession.

If the specified asset belongs to a mutable subclass of AVAsset, AVMutableComposition or AVMutableMovie, the results of any export-related operation are undefined if you mutate the asset after the operation commences. These operations include but are not limited to: 1) testing the compatibility of export presets with the asset, 2) calculating the maximum duration or estimated length of the output file, and 3) the export operation itself.

pub unsafe fn presetName(&self) -> Retained<NSString>

pub unsafe fn asset(&self) -> Retained<AVAsset>

Available on crate feature AVAsset only.

pub unsafe fn outputFileType(&self) -> Option<Retained<AVFileType>>

Available on crate feature AVMediaFormat only.

pub unsafe fn setOutputFileType(&self, output_file_type: Option<&AVFileType>)

Available on crate feature AVMediaFormat only.

Setter for outputFileType.

pub unsafe fn outputURL(&self) -> Option<Retained<NSURL>>

pub unsafe fn setOutputURL(&self, output_url: Option<&NSURL>)

Setter for outputURL.

pub unsafe fn shouldOptimizeForNetworkUse(&self) -> bool

pub unsafe fn setShouldOptimizeForNetworkUse( &self, should_optimize_for_network_use: bool, )

Setter for shouldOptimizeForNetworkUse.

pub unsafe fn allowsParallelizedExport(&self) -> bool

Determines whether or not parallelization can be employed in the export.

On select platforms, there may be opportunities to expedite the export by using additional resources in parallel. If set to YES, export parallelization will be enabled, only if parallelization requirements are met. There will be no error signaled if export parallelization is not achievable, and instead the export will proceed as normal (without parallelization). If set to NO, export parallelization will not be used.

pub unsafe fn setAllowsParallelizedExport( &self, allows_parallelized_export: bool, )

Setter for allowsParallelizedExport.

pub unsafe fn status(&self) -> AVAssetExportSessionStatus

pub unsafe fn error(&self) -> Option<Retained<NSError>>

pub unsafe fn exportAsynchronouslyWithCompletionHandler( &self, handler: &Block<dyn Fn()>, )

Available on crate feature block2 only.

Starts the asynchronous execution of an export session.

Parameter handler: If internal preparation for export fails, the handler will be invoked synchronously. The handler may also be called asynchronously after -exportAsynchronouslyWithCompletionHandler: returns, in the following cases:

1. if a failure occurs during the export, including failures of loading, re-encoding, or writing media data to the output,
2. if -cancelExport is invoked,
3. if export session succeeds, having completely written its output to the outputURL. In each case, AVAssetExportSession.status will signal the terminal state of the asset reader, and if a failure occurs, the NSError that describes the failure can be obtained from the error property.

Initiates an asynchronous export operation and returns immediately.

pub unsafe fn progress(&self) -> c_float

pub unsafe fn cancelExport(&self)

Cancels the execution of an export session.

Cancel can be invoked when the export is running.

impl AVAssetExportSession

AVAssetExportSessionPresets.

pub unsafe fn allExportPresets() -> Retained<NSArray<NSString>>

Returns all available export preset names.

Returns an array of NSStrings with the names of all available presets. Note that not all presets are compatible with all AVAssets.

Returns: An NSArray containing an NSString for each of the available preset names.

pub unsafe fn exportPresetsCompatibleWithAsset( asset: &AVAsset, ) -> Retained<NSArray<NSString>>

👎Deprecated

Available on crate feature AVAsset only.

Returns only the identifiers compatible with the given AVAsset object.

Not all export presets are compatible with all AVAssets. For example an video only asset is not compatible with an audio only preset. This method returns only the identifiers for presets that will be compatible with the given asset. A client should pass in an AVAsset that is ready to be exported. In order to ensure that the setup and running of an export operation will succeed using a given preset no significant changes (such as adding or deleting tracks) should be made to the asset between retrieving compatible identifiers and performing the export operation. This method will access the tracks property of the AVAsset to build the returned NSArray. To avoid blocking the calling thread, the tracks property should be loaded using the AVAsynchronousKeyValueLoading protocol before calling this method.

Parameter asset: An AVAsset object that is intended to be exported.

Returns: An NSArray containing NSString values for the identifiers of compatible export types. The array is a complete list of the valid identifiers that can be used as arguments to initWithAsset:presetName: with the specified asset.

pub unsafe fn determineCompatibilityOfExportPreset_withAsset_outputFileType_completionHandler( preset_name: &NSString, asset: &AVAsset, output_file_type: Option<&AVFileType>, handler: &Block<dyn Fn(Bool)>, )

Available on crate features AVAsset and AVMediaFormat and block2 only.

Performs an inspection on the compatibility of an export preset, AVAsset and output file type. Calls the completion handler with YES if the arguments are compatible; NO otherwise.

Not all export presets are compatible with all AVAssets and file types. This method can be used to query compatibility. In order to ensure that the setup and running of an export operation will succeed using a given preset no significant changes (such as adding or deleting tracks) should be made to the asset between retrieving compatible identifiers and performing the export operation.

Parameter presetName: An NSString specifying the name of the preset template for the export.

Parameter asset: An AVAsset object that is intended to be exported.

Parameter outputFileType: An AVFileType indicating a file type to check; or nil, to query whether there are any compatible types.

Parameter handler: A block called with the compatibility result.

impl AVAssetExportSession

AVAssetExportSessionFileTypes.

pub unsafe fn supportedFileTypes(&self) -> Retained<NSArray<AVFileType>>

Available on crate feature AVMediaFormat only.

pub unsafe fn determineCompatibleFileTypesWithCompletionHandler( &self, handler: &Block<dyn Fn(NonNull<NSArray<AVFileType>>)>, )

Available on crate features AVMediaFormat and block2 only.

Performs an inspection on the AVAsset and Preset the object was initialized with to determine a list of file types the ExportSession can write.

Parameter handler: Called when the inspection completes with an array of file types the ExportSession can write. Note that this may have a count of zero.

This method is different than the supportedFileTypes property in that it performs an inspection of the AVAsset in order to determine its compatibility with each of the session’s supported file types.

impl AVAssetExportSession

AVAssetExportSessionDurationAndLength.

pub unsafe fn timeRange(&self) -> CMTimeRange

Available on crate feature objc2-core-media only.

pub unsafe fn setTimeRange(&self, time_range: CMTimeRange)

Available on crate feature objc2-core-media only.

Setter for timeRange.

pub unsafe fn maxDuration(&self) -> CMTime

👎Deprecated: Use estimateMaximumDurationWithCompletionHandler: instead

Available on crate feature objc2-core-media only.

pub unsafe fn estimatedOutputFileLength(&self) -> c_longlong

👎Deprecated: Use estimateOutputFileLengthWithCompletionHandler: instead

pub unsafe fn fileLengthLimit(&self) -> c_longlong

pub unsafe fn setFileLengthLimit(&self, file_length_limit: c_longlong)

Setter for fileLengthLimit.

pub unsafe fn estimateMaximumDurationWithCompletionHandler( &self, handler: &Block<dyn Fn(CMTime, *mut NSError)>, )

Available on crate features block2 and objc2-core-media only.

Starts the asynchronous execution of estimating the maximum duration of the export based on the asset, preset, and fileLengthLimit associated with the export session.

If fileLengthLimit is not set on the export session, fileLengthLimit will be assumed to be the maximum file size specified by the preset (if any); else infinite.

Parameter handler: A block called with the estimated maximum duration, or kCMTimeInvalid if an error occurs. The error parameter will be non-nil if an error occurs.

pub unsafe fn estimateOutputFileLengthWithCompletionHandler( &self, handler: &Block<dyn Fn(i64, *mut NSError)>, )

Available on crate feature block2 only.

Starts the asynchronous execution of estimating the output file length of the export based on the asset, preset, and timeRange associated with the export session.

If timeRange is not set on the export session, timeRange will be assumed to be the full time range of the asset.

Parameter handler: A block called with the estimated output file length in bytes, if it can be determined; 0 otherwise. The error parameter will be non-nil if an error occurs.

impl AVAssetExportSession

AVAssetExportSessionMetadata.

pub unsafe fn metadata(&self) -> Option<Retained<NSArray<AVMetadataItem>>>

Available on crate feature AVMetadataItem only.

pub unsafe fn setMetadata(&self, metadata: Option<&NSArray<AVMetadataItem>>)

Available on crate feature AVMetadataItem only.

Setter for metadata.

pub unsafe fn metadataItemFilter( &self, ) -> Option<Retained<AVMetadataItemFilter>>

Available on crate feature AVMetadataItem only.

pub unsafe fn setMetadataItemFilter( &self, metadata_item_filter: Option<&AVMetadataItemFilter>, )

Available on crate feature AVMetadataItem only.

Setter for metadataItemFilter.

impl AVAssetExportSession

AVAssetExportSessionMediaProcessing.

pub unsafe fn audioTimePitchAlgorithm( &self, ) -> Retained<AVAudioTimePitchAlgorithm>

Available on crate feature AVAudioProcessingSettings only.

pub unsafe fn setAudioTimePitchAlgorithm( &self, audio_time_pitch_algorithm: &AVAudioTimePitchAlgorithm, )

Available on crate feature AVAudioProcessingSettings only.

Setter for audioTimePitchAlgorithm.

pub unsafe fn audioMix(&self) -> Option<Retained<AVAudioMix>>

Available on crate feature AVAudioMix only.

pub unsafe fn setAudioMix(&self, audio_mix: Option<&AVAudioMix>)

Available on crate feature AVAudioMix only.

Setter for audioMix.

pub unsafe fn videoComposition(&self) -> Option<Retained<AVVideoComposition>>

Available on crate feature AVVideoComposition only.

pub unsafe fn setVideoComposition( &self, video_composition: Option<&AVVideoComposition>, )

Available on crate feature AVVideoComposition only.

Setter for videoComposition.

pub unsafe fn customVideoCompositor( &self, ) -> Option<Retained<ProtocolObject<dyn AVVideoCompositing>>>

Available on crate feature AVVideoCompositing only.

pub unsafe fn audioTrackGroupHandling(&self) -> AVAssetTrackGroupOutputHandling

Defines export policy for handling alternate audio tracks

Specifies the handling of audio tracks that are members of the same alternate track group corresponding to an exported audio track in the source asset. If no audio track group is present, the value of this property has no effect. If necessary, use the trackGroups property of AVAsset to determine whether any audio track groups are present. The AVAudioMix property is not allowed to be used when also specifying alternate track output handling. An exception will be thrown if both are specified.

pub unsafe fn setAudioTrackGroupHandling( &self, audio_track_group_handling: AVAssetTrackGroupOutputHandling, )

Setter for audioTrackGroupHandling.

impl AVAssetExportSession

AVAssetExportSessionMultipass.

pub unsafe fn canPerformMultiplePassesOverSourceMediaData(&self) -> bool

Determines whether the export session can perform multiple passes over the source media to achieve better results.

When the value for this property is YES, the export session can produce higher quality results at the expense of longer export times. Setting this property to YES may also require the export session to write temporary data to disk during the export. To control the location of temporary data, use the property directoryForTemporaryFiles.

The default value is NO. Not all export session configurations can benefit from performing multiple passes over the source media. In these cases, setting this property to YES has no effect.

This property cannot be set after the export has started.

pub unsafe fn setCanPerformMultiplePassesOverSourceMediaData( &self, can_perform_multiple_passes_over_source_media_data: bool, )

Setter for canPerformMultiplePassesOverSourceMediaData.

pub unsafe fn directoryForTemporaryFiles(&self) -> Option<Retained<NSURL>>

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

AVAssetExportSession may need to write temporary files when configured in certain ways, such as when canPerformMultiplePassesOverSourceMediaData is set to YES. This property can be used to control where in the filesystem those temporary files are created. All temporary files will be deleted when the export is completed, is canceled, or fails.

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

This property cannot be set after the export 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).

pub unsafe fn setDirectoryForTemporaryFiles( &self, directory_for_temporary_files: Option<&NSURL>, )

Setter for directoryForTemporaryFiles.

Methods from Deref<Target = NSObject>

pub fn doesNotRecognizeSelector(&self, sel: Sel) -> !

Handle messages the object doesn’t recognize.

See Apple’s documentation for details.

Methods from Deref<Target = AnyObject>

pub fn class(&self) -> &'static AnyClass

Dynamically find the class of this object.

Example

Check that an instance of NSObject has the precise class NSObject.

use objc2::ClassType;
use objc2::runtime::NSObject;

let obj = NSObject::new();
assert_eq!(obj.class(), NSObject::class());

pub unsafe fn get_ivar<T>(&self, name: &str) -> &T

where T: Encode,

👎Deprecated: this is difficult to use correctly, use Ivar::load instead.

Use Ivar::load instead.

Safety

The object must have an instance variable with the given name, and it must be of type T.

See Ivar::load_ptr for details surrounding this.

pub fn downcast_ref<T>(&self) -> Option<&T>

where T: DowncastTarget,

Attempt to downcast the object to a class of type T.

This is the reference-variant. Use Retained::downcast if you want to convert a retained object to another type.

Mutable classes

Some classes have immutable and mutable variants, such as NSString and NSMutableString.

When some Objective-C API signature says it gives you an immutable class, it generally expects you to not mutate that, even though it may technically be mutable “under the hood”.

So using this method to convert a NSString to a NSMutableString, while not unsound, is generally frowned upon unless you created the string yourself, or the API explicitly documents the string to be mutable.

See Apple’s documentation on mutability and on isKindOfClass: for more details.

Generic classes

Objective-C generics are called “lightweight generics”, and that’s because they aren’t exposed in the runtime. This makes it impossible to safely downcast to generic collections, so this is disallowed by this method.

You can, however, safely downcast to generic collections where all the type-parameters are AnyObject.

Panics

This works internally by calling isKindOfClass:. That means that the object must have the instance method of that name, and an exception will be thrown (if CoreFoundation is linked) or the process will abort if that is not the case. In the vast majority of cases, you don’t need to worry about this, since both root objects NSObject and NSProxy implement this method.

Examples

Cast an NSString back and forth from NSObject.

use objc2::rc::Retained;
use objc2_foundation::{NSObject, NSString};

let obj: Retained<NSObject> = NSString::new().into_super();
let string = obj.downcast_ref::<NSString>().unwrap();
// Or with `downcast`, if we do not need the object afterwards
let string = obj.downcast::<NSString>().unwrap();

Try (and fail) to cast an NSObject to an NSString.

use objc2_foundation::{NSObject, NSString};

let obj = NSObject::new();
assert!(obj.downcast_ref::<NSString>().is_none());

Try to cast to an array of strings.

use objc2_foundation::{NSArray, NSObject, NSString};

let arr = NSArray::from_retained_slice(&[NSObject::new()]);
// This is invalid and doesn't type check.
let arr = arr.downcast_ref::<NSArray<NSString>>();

This fails to compile, since it would require enumerating over the array to ensure that each element is of the desired type, which is a performance pitfall.

Downcast when processing each element instead.

use objc2_foundation::{NSArray, NSObject, NSString};

let arr = NSArray::from_retained_slice(&[NSObject::new()]);

for elem in arr {
    if let Some(data) = elem.downcast_ref::<NSString>() {
        // handle `data`
    }
}

Trait Implementations

impl AsRef<AVAssetExportSession> for AVAssetExportSession

fn as_ref(&self) -> &Self

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<AnyObject> for AVAssetExportSession

fn as_ref(&self) -> &AnyObject

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<NSObject> for AVAssetExportSession

fn as_ref(&self) -> &NSObject

Converts this type into a shared reference of the (usually inferred) input type.

impl Borrow<AnyObject> for AVAssetExportSession

fn borrow(&self) -> &AnyObject

Immutably borrows from an owned value.

impl Borrow<NSObject> for AVAssetExportSession

fn borrow(&self) -> &NSObject

Immutably borrows from an owned value.

impl ClassType for AVAssetExportSession

const NAME: &'static str = "AVAssetExportSession"

The name of the Objective-C class that this type represents.

type Super = NSObject

The superclass of this class.

type ThreadKind = <<AVAssetExportSession as ClassType>::Super as ClassType>::ThreadKind

Whether the type can be used from any thread, or from only the main thread.

fn class() -> &'static AnyClass

Get a reference to the Objective-C class that this type represents.

fn as_super(&self) -> &Self::Super

Get an immutable reference to the superclass.

impl Debug for AVAssetExportSession

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Deref for AVAssetExportSession

type Target = NSObject

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl Hash for AVAssetExportSession

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Message for AVAssetExportSession

fn retain(&self) -> Retained<Self>

where Self: Sized,

Increment the reference count of the receiver.

impl NSObjectProtocol for AVAssetExportSession

fn isEqual(&self, other: Option<&AnyObject>) -> bool

where Self: Sized + Message,

Check whether the object is equal to an arbitrary other object.

fn hash(&self) -> usize

where Self: Sized + Message,

An integer that can be used as a table address in a hash table structure.

fn isKindOfClass(&self, cls: &AnyClass) -> bool

where Self: Sized + Message,

Check if the object is an instance of the class, or one of its subclasses.

fn is_kind_of<T>(&self) -> bool

where T: ClassType, Self: Sized + Message,

👎Deprecated: use isKindOfClass directly, or cast your objects with AnyObject::downcast_ref

Check if the object is an instance of the class type, or one of its subclasses.

fn isMemberOfClass(&self, cls: &AnyClass) -> bool

where Self: Sized + Message,

Check if the object is an instance of a specific class, without checking subclasses.

fn respondsToSelector(&self, aSelector: Sel) -> bool

where Self: Sized + Message,

Check whether the object implements or inherits a method with the given selector.

fn conformsToProtocol(&self, aProtocol: &AnyProtocol) -> bool

where Self: Sized + Message,

Check whether the object conforms to a given protocol.

fn description(&self) -> Retained<NSObject>

where Self: Sized + Message,

A textual representation of the object.

fn debugDescription(&self) -> Retained<NSObject>

where Self: Sized + Message,

A textual representation of the object to use when debugging.

fn isProxy(&self) -> bool

where Self: Sized + Message,

Check whether the receiver is a subclass of the NSProxy root class instead of the usual NSObject.

fn retainCount(&self) -> usize

where Self: Sized + Message,

The reference count of the object.

impl PartialEq for AVAssetExportSession

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl RefEncode for AVAssetExportSession

const ENCODING_REF: Encoding = <NSObject as ::objc2::RefEncode>::ENCODING_REF

The Objective-C type-encoding for a reference of this type.

impl DowncastTarget for AVAssetExportSession

impl Eq for AVAssetExportSession