Example Usage for getting markers from Timeline at specific CMTime?

[latenitefilms]

Let's say I want to get all the markers at a specific CMTime reference in a FCPXML.

Here's an example FCPXML (it's been dragged directly from a Project in the Browser):

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE fcpxml>

<fcpxml version="1.11">
    <resources>
        <format id="r1" name="FFVideoFormat1080p25" frameDuration="100/2500s" width="1920" height="1080" colorSpace="1-1-1 (Rec. 709)"/>
        <asset id="r2" name="Test A" uid="34FB0BD07A3BDB5833D18B19ECE2D77D" start="0s" duration="10s" hasVideo="1" format="r1" videoSources="1">
            <media-rep kind="original-media" sig="34FB0BD07A3BDB5833D18B19ECE2D77D" src="file:///Users/chrishocking/Movies/Test%20Clips/Test%20A.mov">
                <bookmark>Ym9va8gDAAAAAAQQMAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAxAIAAAUAAAABAQAAVXNlcnMAAAAMAAAAAQEAAGNocmlzaG9ja2luZwYAAAABAQAATW92aWVzAAAKAAAAAQEAAFRlc3QgQ2xpcHMAAAoAAAABAQAAVGVzdCBBLm1vdgAAFAAAAAEGAAAEAAAAFAAAACgAAAA4AAAATAAAAAgAAAAEAwAAhFwAAAAAAAAIAAAABAMAAGCoAwAAAAAACAAAAAQDAACPqAMAAAAAAAgAAAAEAwAAe26zAQAAAAAIAAAABAMAAI5uswEAAAAAFAAAAAEGAAB8AAAAjAAAAJwAAACsAAAAvAAAAAgAAAAABAAAQcRL7fIgo1gYAAAAAQIAAAEAAAAAAAAADwAAAAAAAAAAAAAAAAAAAAgAAAAEAwAAAwAAAAAAAAAEAAAAAwMAAPUBAAAIAAAAAQkAAGZpbGU6Ly8vDAAAAAEBAABNYWNpbnRvc2ggSEQIAAAABAMAAACA1E5GBwAACAAAAAAEAABBxYSbM4AAACQAAAABAQAAQThCMUEzNDktODg3Mi00QUJFLThDMTQtMzUyQzJBNENFRUQ3GAAAAAECAACBAAAAAQAAAO8TAAABAAAAAAAAAAAAAAABAAAAAQEAAC8AAAAAAAAAAQUAAOIAAAABAgAAM2M4ZjliZTkyMGYwNTZkZjk0MzdhMWE0NGY0YTBiMDg3MWY3ZDNhM2VmNzllOTFlMmU1ZmY4ZjgyMjdkOTZjODswMDswMDAwMDAwMDswMDAwMDAwMDswMDAwMDAwMDswMDAwMDAwMDAwMDAwMDIwO2NvbS5hcHBsZS5hcHAtc2FuZGJveC5yZWFkLXdyaXRlOzAxOzAxMDAwMDBmOzAwMDAwMDAwMDFiMzZlOGU7MDE7L3VzZXJzL2NocmlzaG9ja2luZy9tb3ZpZXMvdGVzdCBjbGlwcy90ZXN0IGEubW92AAAAzAAAAP7///8BAAAAAAAAABAAAAAEEAAAYAAAAAAAAAAFEAAAzAAAAAAAAAAQEAAA+AAAAAAAAABAEAAA6AAAAAAAAAACIAAAxAEAAAAAAAAFIAAANAEAAAAAAAAQIAAARAEAAAAAAAARIAAAeAEAAAAAAAASIAAAWAEAAAAAAAATIAAAaAEAAAAAAAAgIAAApAEAAAAAAAAwIAAA0AEAAAAAAAABwAAAGAEAAAAAAAARwAAAFAAAAAAAAAASwAAAKAEAAAAAAACA8AAA2AEAAAAAAAA=</bookmark>
            </media-rep>
            <metadata>
                <md key="com.apple.proapps.studio.rawToLogConversion" value="0"/>
                <md key="com.apple.proapps.spotlight.kMDItemProfileName" value="HD (1-1-1)"/>
                <md key="com.apple.proapps.studio.cameraISO" value="0"/>
                <md key="com.apple.proapps.studio.cameraColorTemperature" value="0"/>
                <md key="com.apple.proapps.spotlight.kMDItemCodecs">
                    <array>
                        <string>Apple ProRes 422 Proxy</string>
                    </array>
                </md>
                <md key="com.apple.proapps.mio.ingestDate" value="2023-12-12 18:06:09 +1100"/>
            </metadata>
        </asset>
    </resources>
    <project name="Test Project" uid="1C14A86C-00E6-4432-B822-06098CA5BD4D" modDate="2023-12-16 17:56:00 +1100">
        <sequence format="r1" duration="10s" tcStart="0s" tcFormat="NDF" audioLayout="stereo" audioRate="48k">
            <spine>
                <asset-clip ref="r2" offset="0s" name="Test A" duration="10s" tcFormat="NDF">
                    <marker start="76/25s" duration="100/2500s" value="Marker at 00:00:03:01"/>
                    <marker start="173/25s" duration="100/2500s" value="Marker at 00:00:06:23"/>
                </asset-clip>
            </spine>
        </sequence>
    </project>
</fcpxml>

How would I go about this?

[orchetect]

There's a very simple way to scrape all markers from a timeline with one line of code. You need to acquire the project element first, then run the extraction and store the results to query later.

After that, extracted markers will have absolute timecode positions you can access as Timecode instances and you can use those as you see fit. If you have a CMTime position, you can just test it against the cmTimeValue property on Timecode.

I haven't tested this code, but in theory it should work. It truncates subframes in case markers aren't exactly on a frame start so it can compare against the CMTime, which I assume will always be a frame start in your case.

class FCPXMLMarkerLocator {
    let markers: [FinalCutPro.FCPXML.ExtractedMarker]
    
    init?(xmlString: String) async throws {
        guard let data = xmlString.data(using: .utf8) else { return nil }
        let fcpxml = try FinalCutPro.FCPXML(fileContent: data)
        guard let project = fcpxml.allProjects().first else { return nil }
        markers = await project.extract(preset: .markers)
    }
    
    func markers(at cmTime: CMTime) -> [FinalCutPro.FCPXML.ExtractedMarker] {
        markers.filter {
            $0.timecode()?
                .roundedDown(toNearest: .frames)
                .cmTimeValue == cmTime
        }
    }
}

The markers(at:) method returns an array because although unlikely, it's possible for more than one marker to exist at the same timecode. In that case, Final Cut Pro usually hides all but one of the markers in the GUI, but the FCPXML will contain them all.