Screenplay-js NPM

About

ScreenplayJS is a Fountain screenplay parser based on fountain-js and afterwriting-labs.

Have a screenplay written in Fountain and need it converted to an HTML format? ScreenplayJS can do just that.

Documentation

For more detailed info, check out the documentation.

Installation

npm install screenplay-js

yarn add screenplay-js

How to Use

After parsing a screenplay file into text, ScreenplayJS can parse a string and return a ScriptJSON object.

import { FountainParser } from "screenplay-js";

// Read file as a string
const screenplay_string = yourFileReaderFunction(screenplay_file)

// Parse screenplay text
const script_json = FountainParser.parse(screenplay_string);

For an example of reading a FDX file and other use cases read the Use Cases and Examples section.

Updating Configuration

By default, ScreenplayJS parses Fountain tokens such as notes, boneyard, and draft date. It also omits returning a list of tokens. You can enable or disable parsing options in the global config or by passing in parameters to the parse function.

Globally enabling token parsing:

import { FountainParser } from "screenplay-js";

// Enable token parsing
FountainParser.options.tokens = true;

// Read file as a string
const screenplay_string = yourFileReaderFunction(screenplay_file)

// Parse screenplay text
const script_json = FountainParser.parse(screenplay_string);

Enabling token parsing on the function:

import { FountainParser } from "screenplay-js";

// Read file as a string
const screenplay_string = yourFileReaderFunction(screenplay_file)

// Add token parsing to an options object
const your_options = { tokens: true }

// Parse screenplay text
const script_json = FountainParser.parse(screenplay_string, your_options);

Note: It is acceptable to pass in a partial options object. ScreenplayJS will merge your options in with the default config options.

Default Config Options

Option	Required	Default	Type	Description
paginate	false	true	boolean	Whether to paginate the HTML results
lines_per_page	false	"loose"	string	How many approximate lines-per-page, via FinalDraft
script_html	false	false	boolean	Whether to add a HTML string to the returned ScriptJSON object
script_html_array	false	false	boolean	Whether to add an array of HTML strings to the returned ScriptJSON object
notes	false	true	boolean	Whether to parse note tokens from a Fountain file
draft_date	false	true	boolean	Whether to parse the draft date token from a Fountain file
boneyard	false	true	boolean	Whether to parse boneyard tokens from a Fountain file
tokens	false	false	boolean	Whether to add a list of tokens in returned ScriptJSON object

Outputs and Interfaces

ScreenplayJS has various interfaces that can be imported and extended within your project.

Example of importing the IScriptJSON interface.

For more about Interfaces read TypeScript's documentation

import { IScriptJSON } from 'screenplay-js'

ScriptJSON

Field	Type	Description
title	`string`	Title of the script.
credit	`string`	Attribution of the script, i.e. 'Written by'.
authors	`Array<string>`	Authors of the script
source	`string`	Source of the script, i.e. 'Story by...'
notes	`string`	Additional information about the script.
draft_date	`string`	Date of draft in a string format.
date	`string`	Published date of the script.
contact	`string`	Contact information of the authors.
copyright	`string`	Copyright year of the script.
scenes	`Array<string>`	The parsed scenes of a script.
title_page_html	`string`	The HTML of the script title page.
script_html	`string`	The HTML of the parsed script.
script_pages	`IScriptPage[]`	The parsed script broken into pages. Each page is represented by the array index.
script_pages_html	`Array<Array<string>>`	The HTML of the parsed script pages.
script_html_array	`Array<string>`	The HTML for the parsed script.

Token

IToken {
  type?: string,
  text?: string,
  scene_number?: number,
  depth?: number
}

ScriptPage

IScriptPage {
  _id: string;
  html: string;
}

Parser Options

IParserOptions {
  paginate: boolean,
  lines_per_page: 'none' | 'loose' | 'normal' | 'tight' | 'very_tight',
  script_html: boolean,
  script_html_array: boolean,
  notes: boolean,
  draft_date: boolean
  boneyard: boolean,
  tokens: boolean,
}

Examples and Use Cases

GuernseyBros

ScreenplayJS is used in the GuernseyBros project. You can read their latest sketches, spec scripts, or feature length screenplays on their website.

GuernseyBros uses VueJS, Nuxt, and ScreenplayJS to parse Fountain scripts into HTML, providing mobile responsive scripts and screenplays.

Uploading and Converting a FDX File to Fountain

An example of how to upload a Final Draft (FDX) file to Fountain screenplay format can be found in the exaples directory under the fdx-to-fountain sub-directory.