scripttrace

English | 中文

Local screenplay labeling tool. Import Markdown, plain text, or Word; keep the original on the left and rewrite lines on the right. Deletions are marked red, insertions green. Each line can take a “why this change” note and a 1–5 score. Export full JSON or SFT training data.

Everything runs on your machine. Nothing is uploaded to the cloud. Projects are stored under ~/.scripttrace/projects/ by default.

Author: yundong Wu, Zhencheng Li (李振诚) · Package: PyPI · Source: GitHub

Requires Python 3.10+ and a modern browser (Chrome / Edge / Firefox). The app UI is currently Chinese.

Install

pip install scripttrace
scripttrace serve

Open the URL printed in the terminal (default http://127.0.0.1:8765).

Upgrade:

pip install -U scripttrace

With Conda:

conda create -n scripttrace python=3.11 -y
conda activate scripttrace
pip install scripttrace

Run

scripttrace serve

Change port or data directory:

scripttrace serve --port 9000
scripttrace serve -p 9000 --data-dir D:\labels
scripttrace serve --host 0.0.0.0 --port 9000

--host 0.0.0.0 allows LAN access. Use that only on a trusted network.

scripttrace --help
scripttrace serve --help

Flag	Environment variable	Default	Meaning
--host	SCRIPTTRACE_HOST	127.0.0.1	Bind address
-p / --port	SCRIPTTRACE_PORT	8765	Port (1–65535)
--data-dir	SCRIPTTRACE_HOME	~/.scripttrace/projects	Project data directory

Usage

1. Import a screenplay on the left (.md / .txt / .docx; .fountain may work). The project name defaults to the filename; you can rename or delete projects in the list.
2. Three columns:
   • Original: read-only, never overwritten. Deleted text is red.
   • Revised: edit dialogue here. Inserted text is green.
   • Notes / score: explain why it changed; 1–5 stars (click again to clear).
3. Search, filter All / Changed / Unchanged, show annotated only, and jump with Prev / Next.
4. Edits auto-save after about a second. You can also click Save or press Ctrl+S.
5. Preview / Export shows stats and a sample, then download the format you need.

The sidebar can collapse (‹ / ☰). That state is remembered.

Shortcut	Action
Ctrl+S (⌘S on macOS)	Save now
Ctrl+↓ / Ctrl+↑	Next / previous changed line
Esc	Close the preview dialog

A short sample lives in samples/demo.md.

Screenplay format

The parser splits text into episode / scene / dialogue / action blocks. This shape is recognized most reliably:

# Title

## Episode 3

场景：地下车库 夜

**林深**
此事我已知晓，你不必再解释。

苏晚：我只是希望你能理解我的难处。

△ 车灯扫过水泥柱。

• Episode: 第3集 or EPISODE 3
• Scene: 场景：… / 場次 / SCENE, or INT. / EXT. / 内景 / 外景
• Dialogue: a speaker name on its own line (optionally bold), then the line; or Speaker: line
• Action: a line starting with △

Text files are decoded as UTF-8 (with or without BOM) or GB18030. Max upload size is 20MB.

Export formats

Preview / Export switches among three formats. Preview shows only the first few records; download is the full file.

1. Full JSON (*.scripttrace.json)

schema: scripttrace.v1. All blocks, character-level ops, and an SFT array of changed dialogue. Good for archives and downstream tools.

{
  "schema": "scripttrace.v1",
  "title": "示例短剧",
  "blocks": [
    {
      "id": "b0007",
      "kind": "dialogue",
      "speaker": "林深",
      "episode": "3",
      "original": "此事我已知晓，你不必再解释。",
      "revised": "我知道了。别解释。",
      "changed": true,
      "note": "太文言，改口语",
      "score": 4,
      "ops": [
        {"op": "delete", "text": "此事我已知晓，你不必再解释。"},
        {"op": "insert", "text": "我知道了。别解释。"}
      ]
    }
  ],
  "sft": [
    {
      "instruction": "Rewrite the lines so they sound like speech. …",
      "input": "第3集 场次 地下车库 角色 林深\n【原文台词】\n此事我已知晓，你不必再解释。",
      "output": "我知道了。别解释。",
      "note": "太文言，改口语",
      "score": 4
    }
  ]
}

ops are character-level traces: equal / delete / insert.

2. Change trace (*.trace.json)

schema: scripttrace.trace.v1. Changed lines only: deleted / inserted / ops, plus note and score.

3. SFT JSONL (*.sft.jsonl)

Changed dialogue only. One training row per line: instruction / input / output, plus note and score.

Unchanged lines are omitted from the trace and SFT exports.

Where data lives

Each project is a folder under the data directory, with project.json and a copy of the imported file. The original text is immutable on the server; saves only write the rewrite, note, and score.

On Windows the default looks like:

C:\Users\<you>\.scripttrace\projects\

Copy that folder to back up or move machines. --data-dir can point at a drive or share.

FAQ

pip cannot find the package / not the latest version
Use Python ≥ 3.10, then pip install -U scripttrace. If you have several Pythons, use python -m pip install scripttrace.

Page will not load / port in use
Try another port: scripttrace serve -p 9000.

Code changes do not show up
Restart scripttrace serve after Python edits. Hard-refresh the page with Ctrl+F5 so old JS/CSS is not cached.

Preview / Export does nothing
Confirm the server is still running, then Ctrl+F5. Restart the server after an upgrade.

Word layout looks wrong
.docx import keeps paragraph text only. Tables and text boxes may be dropped. Prefer .md or .txt for important scripts.

Develop from source

pip install -e ".[dev]"
pytest

Code is under src/scripttrace/; the UI is under src/scripttrace/static/. An editable install picks up Python changes, but you still need to restart the server.

To publish a new version, bump version in pyproject.toml (e.g. 0.1.1; a version can be uploaded only once), then:

python -m build
twine upload dist/*

License

MIT © yundong Wu, Zhencheng Li (李振诚)