FCPXMLUtility

public struct FCPXMLUtility

Contains miscellaneous utility methods for processing FCPXML data.

Retrieval Methods

  • Returns an array of elements that match specified FCPXML element types.

    Declaration

    Swift

    public func filter(fcpxElements elements: [XMLElement], ofTypes types: [FCPXMLElementType]) -> [XMLElement]

    Parameters

    elements

    An array of XMLElement objects
    types

    An array of FCPXMLElementType enumeration values

    Return Value

    A filtered array of XMLElement objects

Time Conversion Methods

  • Creates a CMTime value that represents real time from timecode values.

    Declaration

    Swift

    public func CMTimeFrom(timecodeHours: Int, timecodeMinutes: Int, timecodeSeconds: Int, timecodeFrames: Int, frameDuration: CMTime) -> CMTime

    Parameters

    timecodeHours

    The hours element of the timecode value.
    timecodeMinutes

    The minutes element of the timecode value.
    timecodeSeconds

    The seconds element of the timecode value.
    timecodeFrames

    The frames element of the timecode value.
    frameDuration

    The duration of a single frame as a CMTime value.

    Return Value

    A CMTime value equivalent to the timecode value in real time.

  • Converts an FCPXML time value to a CMTime value.

    Declaration

    Swift

    public func CMTime(fromFCPXMLTime timeString: String) -> CMTime

    Parameters

    fromFCPXMLTimeString

    The FCPXML time value as a string.

    Return Value

    The equivalent CMTime value.

  • Converts a CMTime value to an FCPXML time value.

    Declaration

    Swift

    public func fcpxmlTime(fromCMTime time: CMTime) -> String

    Parameters

    time

    A CMTime value to convert.

    Return Value

    The FCPXML time value as a string.

  • Conforms a given CMTime value to the frameDuration so that the value falls on an edit frame boundary. The function rounds the edit frame down.

    Declaration

    Swift

    public func conform(time: CMTime, toFrameDuration frameDuration: CMTime) -> CMTime

    Parameters

    time

    A CMTime value to conform.
    frameDuration

    The frame duration to conform to, represented as a CMTime.

    Return Value

    A CMTime of the conformed value.

  • Converts a project counter value to the project’s timecode.

    Declaration

    Swift

    @available(*, deprecated, message: "Use sequenceTimecode(fromCounterValue:inSequence:﹚ instead.")
public func projectTimecode(fromCounterValue counterValue: CMTime, inProject project: XMLElement) -> CMTime?

    Parameters

    counterValue

    The counter value to convert.
    project

    The project to convert against, as an NSXMLElement.

    Return Value

    An optional CMTime value of the timecode value.

  • Converts a project timecode value to the project’s counter time.

    Declaration

    Swift

    @available(*, deprecated, message: "Use sequenceCounterTime(fromTimecodeValue:inSequence:﹚ instead.")
public func projectCounterTime(fromTimecodeValue timecodeValue: CMTime, inProject project: XMLElement) -> CMTime?

    Parameters

    timecodeValue

    The timecode value to convert.
    project

    The project to convert against, as an NSXMLElement.

    Return Value

    An optional CMTime value of the counter time.

  • Converts a sequence counter value to the sequence’s timecode.

    Declaration

    Swift

    public func sequenceTimecode(fromCounterValue counterValue: CMTime, inSequence sequence: XMLElement) -> CMTime?

    Parameters

    counterValue

    The counter value to convert.
    project

    The sequence to convert against, as an NSXMLElement.

    Return Value

    An optional CMTime value of the timecode value.

  • Converts a sequence timecode value to the sequence counter time.

    Declaration

    Swift

    public func sequenceCounterTime(fromTimecodeValue timecodeValue: CMTime, inSequence sequence: XMLElement) -> CMTime?

    Parameters

    timecodeValue

    The timecode value to convert.
    sequence

    The sequence to convert against, as an NSXMLElement.

    Return Value

    An optional CMTime value of the counter time.

  • Converts a local time value to a clip’s parent time value. In FCPXML, this would be converting a time value that is in the start value timescale to the offset value timescale.

    For example, if a clip on the primary storyline has an attached clip, this will convert the attached clip’s offset value to its parent clip’s offset value timescale.

    Declaration

    Swift

    public func parentTime(fromLocalTime localTimeValue: CMTime, forClip clip: XMLElement) -> CMTime?

    Parameters

    fromLocalTime

    The local time value to convert.
    forClip

    The clip to convert against.

    Return Value

    A CMTime value of the resulting parent time value.

  • Converts a parent time value to a clip’s local time value. In FCPXML, this would be converting a time value that is in the offset value timescale to the start value timescale.

    For example, if a clip on the primary storyline has an attached clip, this will tell you what the attached clip’s offset should be based on where you want it to be placed along the primary storyline.

    Declaration

    Swift

    public func localTime(fromParentTime parentTimeValue: CMTime, forClip clip: XMLElement) -> CMTime?

    Parameters

    fromParentTime

    The parent time value to convert.
    forClip

    The clip to convert against.

    Return Value

    A CMTime value of the resulting parent time value.

  • Provides the start time of the given clip within the project timeline.

    Declaration

    Swift

    public func projectTime(forClip clip: XMLElement, inProject project: XMLElement) -> CMTime?

    Parameters

    forClip

    The clip on the timeline to return the start time value for. The clip can be a clip on the primary storyline, a secondary storyline or it can be a connected clip.
    inProject

    The project that the clip resides in.

    Return Value

    A CMTime value of the resulting project time value.

  • Returns the clip’s parent’s equivalent offset timings for the specified in and out times. This is useful for walking up an XMLElement hierarchy in order to get the time values of the clip on the project timeline.

    Declaration

    Swift

    public func parentClipTime(forInTime inTime: CMTime, outTime: CMTime, forClip clip: XMLElement) -> (in: CMTime, out: CMTime, parent: XMLElement)?

    Parameters

    inTime

    The in time to convert, given as a CMTime value.
    outTime

    The out time to convert, given as a CMTime value.
    clip

    The clip that the time values are from. The parent time values will be drawn from this clip’s parent.

    Return Value

    A tuple of the converted in time, the converted out time, and the parent XMLElement of the specified clip.

Other Conversion Methods

  • Converts line breaks in attributes to safe XML entities in an XML file, returning an NSXMLDocument.

    When text values contain line breaks, such as in markers, Final Cut Pro X exports FCPXML files with the line break as is, not encoded into a valid XML line break character. This function will replace line breaks in attribute nodes in FCPXML files with the character entity.

    Declaration

    Swift

    public func convertLineBreaksInAttributes(inXMLDocumentURL URL: Foundation.URL) -> XMLDocument?

    Parameters

    URL

    A URL object pointing to the XML file to convert.

    Return Value

    An XMLDocument or nil if there was a file read or conversion error.

  • Returns the FFVideoFormat identifier based on the given parameters. If the parameters don’t match a defined identifier according to FCPXML v1.5, the method will return the string FFVideoFormatRateUndefined.

    Declaration

    Swift

    public func FFVideoFormat(fromWidth width: Int, height: Int, frameRate: Float, isInterlaced: Bool, isSD16x9: Bool) -> String

    Parameters

    fromWidth

    The width of the frame as an integer.
    height

    The height of the frame as an integer.
    frameRate

    The frame rate as a float.
    isInterlaced

    A boolean value indicating if the format is interlaced.
    is16x9

    A boolean value indicating if the format has an aspect ratio of 16:9.

    Return Value

    A string of the FFVideoFormat identifier.