<a href="https://github.com/TheAcharya/MarkersExtractor"><img src="Assets/MarkersExtractor_Icon.png" height="200"> <h1 align="center">MarkersExtractor (CLI & Library)</h1> <a href="https://github.com/TheAcharya/MarkersExtractor/blob/main/LICENSE"><img src="http://img.shields.io/badge/license-MIT-lightgrey.svg?style=flat" alt="license"/></a> <a href="https://github.com/TheAcharya/MarkerData"><img src="https://img.shields.io/badge/platform-macOS-lightgrey.svg?style=flat" alt="platform"/></a> <a href="https://github.com/TheAcharya/MarkersExtractor/actions/workflows/build.yml"><img src="https://github.com/TheAcharya/MarkersExtractor/actions/workflows/build.yml/badge.svg" alt="build"/></a> <a href="Github All Releases"><img src="https://img.shields.io/github/downloads/TheAcharya/MarkersExtractor/total.svg" alt="release_github"/></a>

Marker metadata extraction and conversion tool and library for Final Cut Pro.

Core Features

Accurately extract markers and captions from FCP's FCPXML/FCPXMLD data export format
Ability to batch extract and render stills or animated GIFs based on each marker's timecode
Ability to batch burn-in labels of each marker's metadata onto the stills or animated GIFs
Fast, multi-threaded operation

Extract Profiles

Notion (JSON) - Compatible with CSV2Notion Neo
Airtable (JSON) - Compatible with Airlift
Generic JSON
Comma-separated values (CSV) - Compatible with spreadsheet applications
Tab-separated values (TSV) - Compatible with spreadsheet application
Microsoft Excel (XLSX)
YouTube Chapters (TXT)
Compressor Chapters (TXT)
Markdown List (MD)
SubRip Subtitle (SRT)
Standard MIDI File - Compatible with most audio DAWs

Installation
Usage
Featured
Utilised By
Credits
License
Reporting Bugs
Contributing

Installation

First, ensure your system is configured to allow the tool to run:

<details><summary>Privacy & Security Settings</summary>

Navigate to the Privacy & Security settings and set your preference to App Store and identified developers.

Pre-Compiled CLI Binary

Download the latest release of the CLI universal binary here.

Extract the markers-extractor-cli-portable-x.x.x.zip file from the release.

Using Homebrew

$ brew install TheAcharya/homebrew-tap/markers-extractor

$ brew uninstall --cask markers-extractor

Upon completion, find the installed binary markers-extractor located within /usr/local/bin. Since this is a standard directory part of the environment search path, it will allow running markers-extractor from any directory like a standard command.

Pre-Compiled CLI Binary (macOS Installer)

Install

Download the latest release of the CLI installer package here.

Use the markers-extractor-cli.pkg installer to install the command-line binary into your system. Upon completion, find the installed binary markers-extractor located within /usr/local/bin. Since this is a standard directory part of the environment search path, it will allow running markers-extractor from any directory like a standard command.

Uninstall

To uninstall, run this terminal command. It will require your account password.

sudo rm /usr/local/bin/markers-extractor

Compiled From Source

VERSION=0.4.3 # replace this with the git tag of the version you need
git clone https://github.com/TheAcharya/MarkersExtractor.git
cd MarkersExtractor
git checkout "tags/$VERSION"
swift build -c release

Once the build has finished, the markers-extractor executable will be located at .build/release/.

Usage

CLI

$ markers-extractor --help
OVERVIEW: Tool to extract markers from Final Cut Pro FCPXML/FCPXMLD.

https://github.com/TheAcharya/MarkersExtractor

USAGE: markers-extractor [<options>] <fcpxml-path> <output-dir>

ARGUMENTS:
  <fcpxml-path>           Input FCPXML file / FCPXMLD bundle.
  <output-dir>            Output directory.

GENERAL:
  --export-format <airtable | compressor | csv | json | markdown | midi | notion | srt | tsv | xlsx | youtube>
                          Metadata export format. (default: csv)
  --enable-subframes      Enable output of timecode subframes.
  --folder-format <short | medium | long>
                          Output folder name format. (default: medium)
  --id-naming-mode <timelineNameAndTimecode | name | notes>
                          Marker naming mode. This affects Marker IDs and image
                          filenames. (default: timelineNameAndTimecode)

MARKER FILTERING:
  --markers-source <markers | markersAndCaptions | captions>
                          Annotations to import. If captions are used, their
                          start timecode determines their position. (default:
                          markers)
  --exclude-role <name>   Exclude markers with a specified role. This argument
                          can be supplied more than once to apply multiple role
                          exclusions.
  --include-disabled      Include markers on disabled clips. By default,
                          disabled clips are ignored.

IMAGE:
  --image-format <png | jpg | gif>
                          Marker thumb image format. 'gif' is animated and
                          additional options can be specified with --gif-fps
                          and --gif-span. (default: png)
  --image-quality <0...100>
                          Image quality percent for JPG. (default: 85)
  --image-width <w>       Limit image width keeping aspect ratio.
  --image-height <h>      Limit image height keeping aspect ratio.
  --image-size-percent <1...100>
                          Limit image size to % keeping aspect ratio. (default
                          for GIF: 50)
  --gif-fps <0.1...60.0>  GIF frame rate. (default: 10.0)
  --gif-span <sec>        GIF capture span around marker. (default: 2.0)
  --use-chapter-marker-thumbnails
                          For chapter markers, use their thumbnail pin position
                          for thumbnail image generation.

LABEL:
  --label <id | name | type | checked | status | notes | reel | scene | take | position | clipType | clipName | clipIn | clipOut | clipDuration | clipKeywords | videoRole | audioRole | eventName | projectName | libraryName | iconImage | imageFileName | xmlPath>
                          Label to overlay on thumb images. This argument can
                          be supplied more than once to apply multiple labels.
  --label-copyright <text>
                          Copyright label. Will be appended after other labels.
  --label-font <name>     Font for image labels. (default: Menlo-Regular)
  --label-font-size <pt>  Maximum font size for image labels, font size is
                          automatically reduced to fit all labels. (default: 30)
  --label-opacity <0...100>
                          Label opacity percent (default: 100)
  --label-font-color <#RRGGBB / #RGB>
                          Label font color (default: #FFF)
  --label-stroke-color <#RRGGBB / #RGB>
                          Label stroke color (default: #000)
  --label-stroke-width <w>
                          Label stroke width, 0 to disable. (default: auto)
  --label-align-horizontal <left | center | right>
                          Horizontal alignment of image labels. (default: left)
  --label-align-vertical <top | center | bottom>
                          Vertical alignment of image labels. (default: top)
  --label-hide-names      Hide names of image labels.

LOG:
  --result-file-path <path>
                          Path including filename to create a JSON result file.
                          If this option is not passed, it won't be created.
  --log <log>             Log file path.
  --log-level <trace | debug | info | notice | warning | error | critical>
                          Log level. (values: trace, debug, info, notice,
                          warning, error, critical; default: info)
  --quiet                 Disable log.
  --no-progress           Disable progress logging.

MEDIA:
  --media-search-path <path>
                          Media search path. This argument can be supplied more
                          than once to use multiple paths. (default: same
                          folder as fcpxml(d))
  --no-media              Bypass media. No thumbnails will be generated.

OPTIONS:
  --version               Show the version.
  -h, --help              Show help information.

Examples

<details><summary>Basic creation of folders and shell script</summary>

For ease of use, usage and creation of shell scripts (.sh files) is recommended.

Create a folder called MarkersExtractor on your Desktop.
Place the latest pre-compiled binary with the folder.
Within that folder, create two more additional folders, Render and Output.
Render is where you pl

MarkersExtractor

Install / Use

README