XMLElement

class XMLElement : XMLNode

Creating FCPXML XMLElement Objects

  • Creates a new event FCPXML XMLElement object.

    Declaration

    Swift

    public func fcpxEvent(name: String) -> XMLElement

    Parameters

    name

    The name of the event in Final Cut Pro X.

    Return Value

    An XMLElement object of the event.

  • Creates a new event FCPXML XMLElement object and adds items to it.

    Declaration

    Swift

    public func fcpxEvent(name: String, items: [XMLElement]) -> XMLElement

    Parameters

    name

    The name of the event in Final Cut Pro X.
    items

    Items to add to the event.

    Return Value

    An XMLElement object of the event.

  • Creates a new project FCPXML XMLElement object and adds clips to it.

    Declaration

    Swift

    public func fcpxProject(name: String, formatRef: String, duration: CMTime, tcStart: CMTime, tcFormat: TimecodeFormat, audioLayout: AudioLayout, audioRate: AudioRate, renderColorSpace: RenderColorSpace, clips: [XMLElement]) -> XMLElement

    Parameters

    name

    The name of the project in Final Cut Pro X.
    formatRef

    The reference ID for the format resource that matches this project.
    duration

    The duration of the clip as a CMTime value.
    tcStart

    The starting timecode of the project timeline as a CMTime value.
    tcFormat

    The TimecodeFormat enum value describing whether the project timecode is drop-frame or non-drop-frame.
    audioLayout

    The project audio channel layout as an AudioLayout enum value.
    audioRate

    The project audio sampling rate as an AudioRate enum value.
    renderColorSpace

    The project render color space as a RenderColorSpace enum value.
    clips

    Clip XMLElement objects to add to the timeline of the project.

    Return Value

    The XMLElement object of the project.

  • Creates a new ref-clip FCPXML XMLElement object

    Declaration

    Swift

    public func fcpxCompoundClip(name: String, ref: String, offset: CMTime?, duration: CMTime, start: CMTime?, useAudioSubroles: Bool) -> XMLElement

    Parameters

    name

    The name of the clip.
    ref

    The reference ID for the resource that this clip refers to.
    offset

    The clip’s location in parent time as a CMTime value.
    duration

    The duration of the clip as a CMTime value.
    start

    The start time of the clip’s local timeline as a CMTime value.
    useAudioSubroles

    A boolean value indicating if the clip’s audio subroles are accessible.

    Return Value

    An XMLElement object of the ref-clip.

  • Creates a new FCPXML multicam reference XMLElement object.

    Declaration

    Swift

    public func fcpxMulticamResource(name: String, id: String, formatRef: String, tcStart: CMTime?, tcFormat: XMLElement.TimecodeFormat, renderColorSpace: XMLElement.RenderColorSpace, angles: [XMLElement]) -> XMLElement

    Parameters

    name

    The name of the resource.
    id

    The unique reference ID of this resource.
    formatRef

    The reference ID of the format that this resource uses.
    tcStart

    The starting timecode value of this resource.
    tcFormat

    The timecode format as an XMLElement.TimecodeFormat enumeration value.
    renderColorSpace

    The color space of this multicam as an XMLElement.TimecodeFormat enumeration value.
    angles

    The mc-angle elements to embed in this multicam resource.

    Return Value

    An XMLElement object of the multicam resource.

  • Creates a new multicam event clip XMLElement object.

    Declaration

    Swift

    public func fcpxMulticamClip(name: String, refID: String, offset: CMTime?, start: CMTime?, duration: CMTime, mcSources: [XMLElement]) -> XMLElement

    Parameters

    name

    The name of the clip.
    refID

    The reference ID.
    offset

    The clip’s location in parent time as a CMTime value.
    duration

    The duration of the clip as a CMTime value.
    mcSources

    An array of mc-source elements to place in this element.

    Return Value

    An XMLElement object of the multicam resource.

  • Creates a new secondary storyline XMLElement object.

    Declaration

    Swift

    public func fcpxSecondaryStoryline(lane: Int, offset: CMTime, formatRef: String?, clips: [XMLElement]) -> XMLElement

    Parameters

    lane

    The lane for the secondary storyline as an Int value.
    offset

    The clip’s location in parent time as a CMTime value.
    formatRef

    The reference ID of the format that this resource uses.
    clips

    An array of XMLElement objects of the clips to be placed inside the secondary storyline.

    Return Value

    An XMLElement object of the secondary storyline element.

  • Creates a new gap to be used in a timeline.

    Declaration

    Swift

    public func fcpxGap(offset: CMTime?, duration: CMTime, start: CMTime?) -> XMLElement

    Parameters

    offset

    The clip’s location in parent time as a CMTime value.
    duration

    The duration of the clip as a CMTime value.
    start

    The start time of the clip’s local timeline as a CMTime value.

    Return Value

    An XMLElement object of the gap.

  • Creates a new title to be used in a timeline.

    Note

    The font, fontSize, fontFace, fontColor, strokeColor, strokeWidth, shadowColor, shadowDistance, shadowAngle, shadowBlurRadius, and alignment properties affect the text style only if the newTextStyle property is true.

    Declaration

    Swift

    public func fcpxTitle(titleName: String, lane: Int?, offset: CMTime, ref: String, duration: CMTime, start: CMTime, role: String?, titleText: String, textStyleID: Int, newTextStyle: Bool, font: String = "Helvetica", fontSize: CGFloat = 62, fontFace: String = "Regular", fontColor: NSColor = NSColor(calibratedRed: 1.0, green: 1.0, blue: 1.0, alpha: 1.0), strokeColor: NSColor? = nil, strokeWidth: Float = 2.0, shadowColor: NSColor? = nil, shadowDistance: Float = 5.0, shadowAngle: Float = 315.0, shadowBlurRadius: Float = 1.0, alignment: TextAlignment = TextAlignment.Center, xPosition: Float = 0, yPosition: Float = 0) -> XMLElement

    Parameters

    titleName

    The name of the title clip on the timeline.
    lane

    The preferred timeline lane to place the clip into.
    offset

    The clip’s location in parent time as a CMTime value.
    ref

    The reference ID for the title effect resource that this clip refers to.
    duration

    The duration of the clip as a CMTime value.
    start

    The start time of the clip’s local timeline as a CMTime value.
    role

    The role assigned to the clip.
    titleText

    The text displayed by this title clip.
    textStyleID

    The ID to assign to a newly generated text style definition or the ID to reference for an existing text style definition.
    newTextStyle

    True if this title clip should contain a newly generated text style definition.
    font

    The font family name to use for the title text.
    fontSize

    The font size.
    fontFace

    The font face.
    fontColor

    The color of the font.
    strokeColor

    The color of the stroke used on the title text.
    strokeWidth

    The width of the stroke.
    shadowColor

    The color of the shadow used underneath the title text.
    shadowDistance

    The distance of the shadow from the title text.
    shadowAngle

    The angle of the shadow offset.
    shadowBlurRadius

    The blur radius of the shadow.
    alignment

    The text paragraph alignment.
    xPosition

    The X position of the text on the screen.
    yPosition

    The Y position of the text on the screen.

    Return Value

    An XMLElement object of the title, which will contain the text style definition, if specified.

  • Creates a new caption to be used in a timeline.

    Declaration

    Swift

    public func fcpxCaption(captionName: String, lane: Int?, offset: CMTime, duration: CMTime, start: CMTime, roleName: String, captionFormat: CaptionFormat, language: CaptionLanguage, captionText: String, CEA_displayStyle: CEA608CaptionDisplayStyle?, CEA_rollUpHeight: Int?, CEA_xPosition: Int?, CEA_yPosition: Int?, CEA_alignment: CEA608CaptionAlignment?, ITT_placement: ITTCaptionPlacement?, textStyleID: Int, newTextStyle: Bool, bold: Bool, italic: Bool, underline: Bool, fontColor: NSColor = NSColor(calibratedRed: 1.0, green: 1.0, blue: 1.0, alpha: 1.0), bgColor: NSColor = NSColor(calibratedRed: 1.0, green: 1.0, blue: 1.0, alpha: 1.0)) -> XMLElement

    Parameters

    captionName

    The name of the caption clip on the timeline.
    lane

    The preferred timeline lane to place the clip into.
    offset

    The clip’s location in parent time as a CMTime value.
    duration

    The duration of the clip as a CMTime value.
    start

    The start time of the clip’s local timeline as a CMTime value.
    roleName

    The role name assigned to the clip.
    captionFormat

    The format of the captions, either ITT or CEA-608, using the CaptionFormat enum.
    language

    The language of the caption text as a CaptionLanguage enum value.
    captionText

    The text displayed by this caption clip.
    textStyleID

    The ID to assign to a newly generated text style definition or the ID to reference for an existing text style definition.
    newTextStyle

    True if this title clip should contain a newly generated text style definition.
    bold

    True if the text is styled bold.
    italic

    True if the text is styled italic.
    underline

    True if the text is styled underline.
    fontColor

    The color of the font as an NSColor value.
    bgColor

    The background color behind the text as an NSColor value. Includes alpha value for semi-transparent and transparent backgrounds for CEA-608 captions.

    Return Value

    An XMLElement object of the caption, which will contain the text style definition, if newTextStyle is true.

Properties for Attribute Nodes

  • Undocumented

    Declaration

    Swift

    public var fcpxType: FCPXMLElementType { get }

  • Undocumented

    Declaration

    Swift

    public var fcpxName: String? { get set }

  • Undocumented

    Declaration

    Swift

    public var fcpxDuration: CMTime? { get set }

  • Undocumented

    Declaration

    Swift

    public var fcpxTCStart: CMTime? { get set }

  • Undocumented

    Declaration

    Swift

    public var fcpxStart: CMTime? { get set }

  • If this element’s fcpxStart property is nil, fcpxStartValue returns a CMTime value of zero. Otherwise, it returns the same value as fcpxStart. This property is used when you want the value of the start attribute whether or not it exists. Final Cut Pro X omits the start attribute when the element starts at 0.

    Declaration

    Swift

    public var fcpxStartValue: CMTime { get }

  • Undocumented

    Declaration

    Swift

    public var fcpxOffset: CMTime? { get set }

  • Undocumented

    Declaration

    Swift

    public var fcpxTCFormat: TimecodeFormat? { get set }

  • Undocumented

    Declaration

    Swift

    public var fcpxFormatRef: String? { get set }

  • Undocumented

    Declaration

    Swift

    public var fcpxRefOrID: String? { get }

  • Returns and sets the ref attribute of an element. If the element fcpxType is FCPXMLElementType.clip, this will return or set its video or audio child element’s ref attribute.

    Declaration

    Swift

    public var fcpxRef: String? { get set }

  • Undocumented

    Declaration

    Swift

    public var fcpxID: String? { get set }

  • This value indicates whether the clip is enabled or disabled. By default, the element attribute is not included in FCPXML exports when the clip is enabled.

    Declaration

    Swift

    public var fcpxEnabled: Bool { get set }

  • Undocumented

    Declaration

    Swift

    public var fcpxRole: String? { get set }

  • Undocumented

    Declaration

    Swift

    public var fcpxLane: Int? { get set }

  • Undocumented

    Declaration

    Swift

    public var fcpxNote: String? { get set }

  • Undocumented

    Declaration

    Swift

    public var fcpxValue: String? { get set }

  • Undocumented

    Declaration

    Swift

    public var fcpxSrc: URL? { get set }

  • Undocumented

    Declaration

    Swift

    public var fcpxFrameDuration: CMTime? { get set }

  • Undocumented

    Declaration

    Swift

    public var fcpxWidth: Int? { get set }

  • Undocumented

    Declaration

    Swift

    public var fcpxHeight: Int? { get set }

  • Undocumented

    Declaration

    Swift

    public var fcpxAudioLayout: AudioLayout? { get set }

  • Undocumented

    Declaration

    Swift

    public var fcpxAudioRate: AudioRate? { get set }

  • Undocumented

    Declaration

    Swift

    public var fcpxRenderColorSpace: RenderColorSpace? { get set }

  • Undocumented

    Declaration

    Swift

    public var fcpxHasAudio: Bool? { get set }

  • Undocumented

    Declaration

    Swift

    public var fcpxHasVideo: Bool? { get set }

  • Undocumented

    Declaration

    Swift

    public var fcpxAngleID: String? { get set }

  • The srcEnable attribute for mc-source multicam clip angles

    Declaration

    Swift

    public var fcpxSrcEnable: MulticamSourceEnable? { get set }

  • Undocumented

    Declaration

    Swift

    public var fcpxUID: String? { get set }

Timing Properties

  • The start of this element on its parent timeline. For example, if this is a video clip on the primary storyline, this value would be the in point of the clip on the project timeline. If this is a clip on a secondary storyline, this value would be the in point of the clip on the secondary storyline’s timeline.

    Declaration

    Swift

    public var fcpxParentInPoint: CMTime? { get set }

  • The end of this element on its parent timeline. For example, if this is a video clip on the primary storyline, this value would be the out point of the clip on the project timeline. If this is a clip on a secondary storyline, this value would be the out point of the clip on the secondary storyline’s timeline.

    Declaration

    Swift

    public var fcpxParentOutPoint: CMTime? { get set }

  • The start of this element’s local timeline. For example, if this is a video clip, this value would be the in point of the clip’s source footage.

    Declaration

    Swift

    public var fcpxLocalInPoint: CMTime { get set }

  • The end of this element’s local timeline. For example, if this is a video clip, this value would be the out point of the clip’s source footage. If this element has no duration, this property will return nil.

    Declaration

    Swift

    public var fcpxLocalOutPoint: CMTime? { get set }

  • The start time of this element on the project timeline.

    Declaration

    Swift

    public var fcpxTimelineInPoint: CMTime? { get }

  • The end time of this element on the project timeline.

    Declaration

    Swift

    public var fcpxTimelineOutPoint: CMTime? { get }

Caption Element Properties

  • The display style for CEA-608 formatted captions.

    Declaration

    Swift

    public var fcpxCEACaptionDisplayStyle: CEA608CaptionDisplayStyle? { get set }

  • The number of rows to show concurrently on the video when the CEA-608 display style is set to roll-up. Valid values are from 2 to 4.

    Declaration

    Swift

    public var fcpxCEACaptionRollUpHeight: Int? { get set }

  • The X position for CEA-608 captions. Valid values are from 1 to 23. Setting this variable will retain the current Y value if it exists. If it does not, the Y value will default to 15.

    Declaration

    Swift

    public var fcpxCEACaptionPositionX: Int? { get set }

  • The Y position for CEA-608 captions. Valid values are from 1 to 15. Setting this variable will retain the current X value if it exists. If it does not, the X value will default to 1.

    Declaration

    Swift

    public var fcpxCEACaptionPositionY: Int? { get set }

  • The caption placement for ITT formatted captions.

    Declaration

    Swift

    public var fcpxITTCaptionPlacement: ITTCaptionPlacement? { get set }

  • The alignment for CEA-608 formatted captions.

    Declaration

    Swift

    public var fcpxCEACaptionAlignment: CEA608CaptionAlignment? { get set }

Element Identification

  • True if this XMLElement is an event.

    Declaration

    Swift

    public var isFCPXEvent: Bool { get }

  • True if this XMLElement is an item in an event, not a resource.

    Declaration

    Swift

    public var isFCPXEventItem: Bool { get }

  • True if this XMLElement is a resource, not an event item.

    Declaration

    Swift

    public var isFCPXResource: Bool { get }

  • True if this XMLElement is an element that can appear on a storyline.

    Declaration

    Swift

    public var isFCPXStoryElement: Bool { get }

  • If this XMLElement is a story element or clip in a sequence, this property returns its location in the sequence.

    Declaration

    Swift

    public var fcpxStoryElementLocation: StoryElementLocation? { get }

Retrieving Related Elements

  • If this is a project element, this returns its sequence element. Returns nil if there is no sequence element or if this is not a project element.

    Declaration

    Swift

    public var fcpxProjectSequence: XMLElement? { get }

  • If this is a project element, this returns the spine of the primary storyline. Returns nil if there is no spine or if this is not a project element.

    Declaration

    Swift

    public var fcpxProjectSpine: XMLElement? { get }

  • If this is a project element, this returns the clips contained within the project. Returns an empty array if there are no clips or if this is not a valid project element.

    Declaration

    Swift

    public var fcpxProjectClips: [XMLElement] { get }

  • If this is a compound clip or compound resource element, this returns its resource’s sequence element. Returns nil if there is no sequence element or if this is not a compound clip or resource element.

    Declaration

    Swift

    public var fcpxCompoundResourceSequence: XMLElement? { get }

  • If this is a compound clip or compound resource element, this returns the spine of the primary storyline. Returns nil if there is no spine or if this is not a compound clip or resource element.

    Declaration

    Swift

    public var fcpxCompoundResourceSpine: XMLElement? { get }

  • If this is a sequence element, this returns the clips contained within the primary storyline. Returns an empty array if there are no clips or if this is not a valid sequence element.

    Declaration

    Swift

    public var fcpxSequenceClips: [XMLElement] { get }

  • If this is an event item, the event that contains it. Returns nil if it is not an event item.

    Declaration

    Swift

    public var fcpxParentEvent: XMLElement? { get }

  • If this is an event item, the XMLElement of its corresponding resource.

    Declaration

    Swift

    public var fcpxResource: XMLElement? { get }

  • An array of the annotation XMLElements within this event item or resource.

    Declaration

    Swift

    public var fcpxAnnotations: [XMLElement] { get }

  • An array of this element’s metadata elements. Returns nil if this element is not a resource or event item.

    Declaration

    Swift

    public var fcpxMetadata: [XMLElement]? { get }

  • An array of mc-angle elements within a multicam media resource. Returns nil if this element is not a multicam media resource.

    Declaration

    Swift

    public var fcpxMulticamAngles: [XMLElement]? { get }

  • Returns clips from an event that match this resource. If this method is called on an XMLElement that is not a resource, nil will be returned. If there are no matching clips in the event, an empty array will be returned.

    Declaration

    Swift

    public func referencingClips(inEvent event: XMLElement) -> [XMLElement]?

    Parameters

    event

    The event XMLElement to search.

    Return Value

    An optional array of XMLElement objects.

Methods for FCPX Library Events

  • Returns all items contained within this event. If this is not an event, the property will be nil. If the event is empty, the property will be an empty array.

    Declaration

    Swift

    public var eventItems: [XMLElement]? { get }

  • Returns the projects contained within this event. If this is not an event, the property will be nil. If the event has no projects, the property will be an empty array.

    Declaration

    Swift

    public var eventProjects: [XMLElement]? { get }

  • Returns the clips contained within this event, excluding the projects. If this is not an event, the property will be nil. If the event has no clips, the property will be an empty array.

    Declaration

    Swift

    public var eventClips: [XMLElement]? { get }

  • Returns all clips in an event that match the given resource ID. If this method is called on an XMLElement that is not an event, nil will be returned. If there are no clips that match the resourceID, an empty array will be returned.

    Throws

    An error if this element is not an event.

    Declaration

    Swift

    public func eventClips(forResourceID resourceID: String) throws -> [XMLElement]

    Parameters

    resourceID

    A string of the resourceID value.

    Return Value

    An array of XMLElement objects that refer to the matching clips. Note that multiple clips in an event can refer to a single resource ID.

  • Declaration

    Swift

    public func eventClips(containingResource resource: XMLElement) throws -> [XMLElement]

    Return Value

  • Adds an item to this event. If this XMLElement is not an event, an error is thrown.

    Throws

    FCPXMLElementError.notAnEvent if the element is not an event.

    Declaration

    Swift

    public func addToEvent(item: XMLElement) throws

    Parameters

    item

    The item to add as an XMLElement.

  • Adds multiple items to this event. If this XMLElement is not an event, an error is thrown.

    Throws

    FCPXMLElementError.notAnEvent if the element is not an event.

    Declaration

    Swift

    public func addToEvent(items: [XMLElement]) throws

    Parameters

    items

    An array of XMLElement items to add.

  • Removes an item from this event. If this XMLElement is not an event, an error is thrown.

    Note

    Use XMLElement.index to obtain the index value to use in the itemIndex parameter.

    Throws

    FCPXMLElementError.notAnEvent if the element is not an event.

    Declaration

    Swift

    public func removeFromEvent(itemIndex: Int) throws

    Parameters

    itemIndex

    The index of the XMLElement to remove.

  • Removes a group of items from this event. If this XMLElement is not an event, an error is thrown.

    Note

    Use XMLElement.index to obtain the index values to use in the itemIndex parameter.

    Throws

    FCPXMLElementError.notAnEvent if the element is not an event.

    Declaration

    Swift

    public func removeFromEvent(itemIndexes: [Int]) throws

    Parameters

    itemIndexes

    An array of the indexes of the XMLElements to remove.

  • Removes a group of items from this event. If this XMLElement is not an event, an error is thrown.

    Throws

    FCPXMLElementError.notAnEvent if the element is not an event.

    Declaration

    Swift

    public func removeFromEvent(items: [XMLElement]) throws

    Parameters

    items

    An array of event item XMLElement objects.

Methods for Event Clips

  • Adds an annotation XMLElement to this item, maintaining the proper order of the DTD. Conforms to FCPXML DTD v1.6.

    Throws

    Throws an error if an annotation cannot be added to this type of FCPXML element or if the element to add is not an annotation.

    Declaration

    Swift

    public func addToClip(annotationElements elements: [XMLElement]) throws

    Parameters

    annotationElements

    The annotations to add as an array of XMLElement objects.

Methods for Projects

  • Returns an array of all roles used inside the project.

    Declaration

    Swift

    public func projectRoles() -> [String]

    Return Value

    An array of roles as String values.

Retrieving Format Information

  • Returns an element’s associated format name, ID, frame duration, and frame size.

    Declaration

    Swift

    public func formatValues() -> (formatID: String, formatName: String, frameDuration: CMTime?, frameSize: CGSize?)?

    Return Value

    A tuple with a formatID string, formatName string, frameDuration CMTime, and frameSize CGSize.

Comparing Timing Between Clips

  • Tests if this clip’s in and out points include the given time value.

    Declaration

    Swift

    public func clipRangeIncludes(_ time: CMTime) -> Bool

    Parameters

    time

    A CMTime value

    Return Value

    True if the time value is between the in and out points of the clip

  • Tests if this clip’s timing falls within the given in and out points.

    Declaration

    Swift

    public func clipRangeIsEnclosedBetween(_ inPoint: CMTime, outPoint: CMTime) -> Bool

    Parameters

    inPoint

    The in point to test against.
    outPoint

    The out point to test against.

    Return Value

    True if the clip’s timing falls within the inPoint and outPoint values.

  • Returns whether the clip overlaps with a given time range specified by an in and out point.

    • Example:\ The following is a reference for how a clip could overlap. Below each case are resulting values for the overlaps, withClipInPoint, and withClipOutPoint tuple values.\ [ comparisonClip ] [ comparisonClip ] [ comparisonClip ]\ [ clip1 ] [ clip2 ] [ clip ] [ clip ]\ (t,f,t) (t,t,f) (true, false, false) (true, true, true)\

    Declaration

    Swift

    public func clipRangeOverlapsWith(_ inPoint: CMTime, outPoint: CMTime) -> (overlaps: Bool, withClipInPoint: Bool, withClipOutPoint: Bool)

    Parameters

    inPoint

    The in point as a CMTime value.
    outPoint

    The out point as a CMTime value.

    Return Value

    A tuple containing three boolean values. Overlaps indicates whether the clip overlaps at all with the in and out point range. withClipInPoint indicates whether the element’s in point overlaps with the range. withClipOutPoint indicates whether the element’s out point overlaps with the range.

  • Returns child elements that fall within the specified in and out points. The element type can optionally be specified.

    Declaration

    Swift

    public func childElementsWithinRangeOf(_ inPoint: CMTime, outPoint: CMTime, elementType: FCPXMLElementType?) -> [(XMLElement: XMLElement, overlapsInPoint: Bool, overlapsOutPoint: Bool)]

    Parameters

    inPoint

    The in point as a CMTime value.
    outPoint

    The out point as a CMTime value.
    elementType

    The element type as an FCPXMLElementType enum value. If the value is nil, the method will return all child elements that match the criteria.

    Return Value

    An array of tuples. Each tuple contains the XML Element as an NSXMLElement, a boolean value indicating whether the element’s in point overlaps with the range, and a boolean value indicating whether the element’s out point overlaps with the range.

Miscellaneous

  • The FCPXML document as a properly formatted string.

    Declaration

    Swift

    public var fcpxmlString: String { get }

  • Retrieves the URLs from the elements contained within this resource.

    Declaration

    Swift

    public func urls() -> [URL]

    Return Value

    An array of NSURLs.

  • Searches the given element and its sub-elements for references and returns them.

    Declaration

    Swift

    public func allReferenceIDs() -> [String]?

    Return Value

    The references as an array of strings or nil if no reference is found.

  • This function goes through the element and all of its sub-elements, finding elements that match the given name. For example, this function can search a sequence and any embedded secondary storylines for matching elements.

    Declaration

    Swift

    public func subelements(forName name: String, usingAbsoluteMatch: Bool) -> [XMLElement]

    Parameters

    forName

    A String of the element name to match with.
    usingAbsoluteMatch

    A boolean value of whether names must match absolutely or whether element names containing the string will yield a match.

    Return Value

    An array of matching elements as XMLElement objects.

  • This function returns all clips within an element and its sub-elements.

    Note

    The clips in the resulting array are not ordered by where they appear in the XML document.

    Declaration

    Swift

    public func clips() -> [XMLElement]

    Return Value

    An array of clips as XMLElement objects.

  • This function goes through the element and all its sub-elements, returning all clips that match the given FCPX clip name.

    Declaration

    Swift

    public func clips(forFCPXName fcpxName: String, usingAbsoluteMatch: Bool) -> [XMLElement]

    Parameters

    fcpxName

    A String of the clip name in FCPX to match with.
    usingAbsoluteMatch

    A boolean value of whether names must match absolutely or whether clip names containing the string will yield a match.

    Return Value

    An array of matching clips as XMLElement objects.

  • This function goes through the element and all its sub-elements, finding clips that match the given type.

    Declaration

    Swift

    public func clips(forElementType elementType: FCPXMLElementType) -> [XMLElement]

    Parameters

    elementType

    A type of FCPXML element as FCPXMLElementType enumeration.

    Return Value

    An array of matching clips as XMLElement objects.

XMLElement Helper Properties and Methods

  • Undocumented

    Declaration

    Swift

    public func getElementAttribute(_ name: String) -> String?

  • Undocumented

    Declaration

    Swift

    public func setElementAttribute(_ name: String, value: String?)

  • Returns the next element in document order.

    Declaration

    Swift

    public var nextElement: XMLElement? { get }

    Return Value

    An XMLElement object or nil if there is no other element after the current one.

  • Returns all sub-elements of this XMLElement.

    Declaration

    Swift

    public func subElements() -> [XMLElement]

    Return Value

    An array of XMLElement objects.

  • Returns the first sub-element with the given element name.

    Declaration

    Swift

    public func subElement(named name: String) -> XMLElement?

    Parameters

    named

    A string of the element name to match.

    Return Value

    An XMLElement object or nil if there was no match.

  • Returns the parent XMLElement.

    Declaration

    Swift

    public var parentElement: XMLElement? { get }

  • Adds an element as a child to this element, placing it in proper order according to the DTD.

    Declaration

    Swift

    public func addChildConformingToDTD(element: XMLElement, overrideDTDVersion: String?)

    Parameters

    element

    The child element to insert.
    overrideDTDVersion

    A string of the DTD filename to override with. The DTD must be stored in the framework. If nil, the function uses the latest DTD version.

  • Converts a whitespace-only text value inside an XMLElement into an XMLNode object and inserts it as a child back into the XMLElement.

    When text values consist of only whitespace characters, such as in title clips with adjusted kerning, Final Cut Pro X exports FCPXML files with the whitespace as is, not encoded into a valid XML whitespace character. This results in the XMLNode class ignoring the whitespace character and not initializing that into an XMLNode object.

    This method extracts the text value inside an XML element string, converts that into a text XMLNode object, and inserts it back into the XMLElement object.

    For example, an XMLElement consisting of:

    <text-style ref="ts30"> </text-style>

    will have its single space character converted into a text XMLNode after being processed through this method.

    Note

    If the XMLElement has a child node, the XMLElement will not be modified.

    Declaration

    Swift

    public func convertWhitespaceText()

Constants

  • Undocumented

    See more

    Declaration

    Swift

    public enum TextAlignment : String

  • Undocumented

    See more

    Declaration

    Swift

    public enum TimecodeFormat : String

  • Undocumented

    See more

    Declaration

    Swift

    public enum AudioLayout : String

  • Undocumented

    See more

    Declaration

    Swift

    public enum AudioRate : String

  • Undocumented

    See more

    Declaration

    Swift

    public enum RenderColorSpace : String

  • Undocumented

    See more

    Declaration

    Swift

    public enum MulticamSourceEnable : String

  • The caption format included in caption role attributes.

    See more

    Declaration

    Swift

    public enum CaptionFormat : String

  • RFC 5646 language tags for use in caption role attributes. The languages included in this enum are those supported by FCPX.

    See more

    Declaration

    Swift

    public enum CaptionLanguage : String

  • Caption display style for CEA-608 captions

    See more

    Declaration

    Swift

    public enum CEA608CaptionDisplayStyle : String

  • Caption placement for ITT captions.

    See more

    Declaration

    Swift

    public enum ITTCaptionPlacement : String

  • Caption alignment for CEA-608 captions.

    See more

    Declaration

    Swift

    public enum CEA608CaptionAlignment : String

  • Color values for CEA-608 captions. The raw value is the color expressed as red green blue alpha which is the way it is represented in FCPXML text style elements.

    See more

    Declaration

    Swift

    public enum CEA608Color : String

  • The location of a story element within its sequence or timeline.

    • primaryStoryline: The story element exists on the primary storyline.
    • attachedClip: The story element is attached to another clip that is on the primary storyline.
    • secondaryStoryline: The story element is embedded in a secondary storyline.
    See more

    Declaration

    Swift

    public enum StoryElementLocation