screenplay-js

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.

This example is a TypeScript example written in VueJS. Feel free to copy-and-paste or convert it to the language of your choosing.

Additional Examples

More examples will be added in the future. Check them out in the example directory!

License

MIT