Metadata-Version: 2.4
Name: scripttrace
Version: 0.1.1
Summary: Local screenplay labeling: upload Markdown/Word, side-by-side edit with change traces, export JSON.
Author: yundong Wu
License: MIT
Project-URL: Homepage, https://github.com/windowssr/scripttrace
Project-URL: Repository, https://github.com/windowssr/scripttrace
Project-URL: Issues, https://github.com/windowssr/scripttrace/issues
Keywords: screenplay,annotation,diff,sft,labeling
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: End Users/Desktop
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn[standard]>=0.27
Requires-Dist: python-docx>=1.1
Requires-Dist: python-multipart>=0.0.9
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Dynamic: license-file

# scripttrace

[English](README.md) | [中文](README.zh-CN.md)

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 · Package: [PyPI](https://pypi.org/project/scripttrace/) · Source: [GitHub](https://github.com/windowssr/scripttrace)

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

## Install

```bash
pip install scripttrace
scripttrace serve
```

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

Upgrade:

```bash
pip install -U scripttrace
```

With Conda:

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

## Run

```bash
scripttrace serve
```

Change port or data directory:

```bash
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.

```bash
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`](samples/demo.md).

## Screenplay format

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

```markdown
# 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.

```json
{
  "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

```bash
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:

```bash
python -m build
twine upload dist/*
```

## License

[MIT](LICENSE) © yundong Wu
