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