Zaturrby/edl-genius

An ES6 module to parse Edit Decision Lists

edl-genius ·

An ES6 module to parse Edit Decision Lists. Currently, only CMX 3600 EDLs are supported, but I plan to include support for File129.

Installing / Getting started

$ npm install --save edl-genius

const EDL = require('edl-genius');

let e = new EDL(29.97);
edl.read('/path/to/your/edl')
  .then((edl) => {
    console.log(edl.events);
  })

/*
[ Event {
    sourceFrameRate: 29.97,
    recordFrameRate: 29.97,
    number: 1,
    reel: 'ACC112',
    trackType: 'V',
    transition: 'C',
    sourceStart: Timecode { frameRate: 29.97, frameCount: 197203 },
    sourceEnd: Timecode { frameRate: 29.97, frameCount: 197400 },
    recordStart: Timecode { frameRate: 29.97, frameCount: 107892 },
    recordEnd: Timecode { frameRate: 29.97, frameCount: 108089 },
    sourceClip: 'ACC112 WARBIRDS.NEW.01',
    sourceFile: 'ACC112 WARBIRDS' },
  Event {
    sourceFrameRate: 29.97,
    recordFrameRate: 29.97,
    number: 2,
    ...
*/

Developing

Built With

This package was built in an environment running Node.js 10.0.0. Travis CI is used to check builds against the latest Node.js and the latest LTS release of Node.js (10.7.0 and 8.11.3 as of this writing).

The only development dependencies are packages needed for testing and linting. I use Mocha for testing and Istanbul to check test coverage.

Setting up Dev

git clone https://github.com/bradcordeiro/edl-genius.git
cd edl-genius/
npm install

Versioning

This package uses Semantic Versioning.

Tests

The goal is to have 100% test coverage of all edge cases. Tough when you're dealing with EDLs, a text exchange format that some vendors deviate from. All pull requests are welcome, and if you'd like to submit a pull request with additional tests, without changing the package code, that's totally cool.

npm test

To run the tests using Mocha.

npm run test-coverage

To get a code coverage report.

Style guide

This package was written using the Airbnb Style Guide. An [.eslintrc.json] file is included in source control, and ESLint as well as the Airbnb plugin are included as development dependencies.

API Reference

The goal of this module is really just to get information out of a text EDL and into JavaScript native data types. Each class defined by this module is really just object storage, with methods to get the information into those objects.

Timecode objects are created using timecode-boss module, which I also wrote. You can check its repository for its API. A common method of Timecode objects you'll probably want to use is toString().

EDL Class

Constructor
new EDL(frameRate : Number)
Returns an empty EDL, with its record frame rate set to the argument. The record frame rate defaults to 29.97 (a.k.a. 30 drop-frame) if omitted. The record frame rate is the frame rate of the sequence the EDL represents, as opposed to the frame rate of the source material in it, which is parsed by this package.

Properties

Name	Type	Description
frameRate	Number	The record frame rate (i.e. the frame rate of the video sequence the EDL describes)
events	[Event]	An array of Events found in the EDL. (See Event class description below)

Methods

Method	Argument Type	Return Type	Description
read(file)	String	Promise	Reads the file argument, and stores the found EDL Events in the EDL object's events property. The Promise Resolver is given the EDL object as its argument.
toJSON(stringify)	Boolean	Object or String	Returns a JSON-strigifiable object if stringify is false, or a JSON string if stringify is true
filterDuplicateMultitrack()	none	EDL	Returns a new EDL with duplicate events removed (ignoring track number).

Event Class

Constructor
new Event(input : String, sourceFrameRate : Number, recordFrameRate : Number)
Parses the passed string into class properties, using the sourceFrameRate for source timecodes and recordFrameRate for record timecodes. If called with no arguments, an empty Event is created, whose properties can be set manually. IF no sourceFrameRate or recordFrameRate are passed, they default to 29.97.

Properties

For clarity, here is an example event that EDL could parse:

004  QEVL1GRN V2    C        01:31:44:03 01:31:44:12 01:00:02:24 01:00:03:01
M2   QEVL1GRN       037.5                01:31:44:03
* GETTY IMAGES__QEVL1GRND130_UNDERGROUND_EL CHAPO TUNNELS_INTERIOR OF ALCATRAZ PRI
* SON. ROW OF CELLS, CLOSE-UP OF CELL DOOR BARS, INSIDE OF JAIL CELL_180563302
* SOURCE FILE: QEVL1GRND130.MOV
* FROM CLIP NAME:  QEVL1GRND130.NEW.01

Name	Type	Description	Example (referencing above event)
number	Number	The event number of the event in the EDL	4
reel	String	A short (generally 8 character) name of the source clip.	QEVL1GRN
trackType	String	A single character for the type of track (V for video, A for audio).	V
trackNumber	Number	A track number, for EDLs that describe multi-track sequences.	2
transition	String	A transition type, generally C for a cut, or W000 for another transition.	C
sourceStart	Timecode	The start of the source clip for the event.	01:31:44:03
sourceEnd	Timecode	The end of the source clip for the event.	01:31:44:12
recordStart	Timecode	The start of the clip's position in the sequence	01:00:02:24
recordEnd	Timecode	The end of the clip's position in the sequence	01:00:03:01
motionEffect	MotionEffect	Any speed-change applied to the clip (see MotionEffect class below)	{ reel: 'QEVL1GRN', speed: 37.5, entryPoint: 01:31:44:03 }
sourceFile	String	The source file name for the source clip	QEVL1GRND130.MOV
sourceClip	String	The clip name from the editing system that generated the EDL	QEVL1GRND130.NEW.01
comment	String	Any miscellaneous comments added to the event in the EDL	GETTY IMAGES__QEVL1GRND130_UNDERGROUND_EL CHAPO TUNNELS_INTERIOR OF ALCATRAZ PRISON. ROW OF CELLS, CLOSE-UP OF CELL DOOR BARS, INSIDE OF JAIL CELL_180563302

MotionEffect Class

Constructor
new MotionEffect(input : String)
Parses the passed string into class properties. If called with no arguments, an empty MotionEffect is created, whose properties can be set manually.

For clarity, here is an example motion effect that EDL could parse (this is also in the Event example above):

M2   QEVL1GRN       037.5                01:31:44:03

Properties

Name	Type	Description	Example (referencing above event)
reel	String	A short source reference for the clip	'QEVL1GRN'
speed	Number	The frame rate at which the source clip is to be played	37.5
entryPoint	Timecode	The start time of the source clip being effected	01:31:44:03

Licensing

Released under the MIT License.