# Lapian Notes: A Local, AI-Assisted Film Breakdown Notebook

> Lapian Notes turns a film into an editable shot-by-shot study notebook with local frame extraction, AI-assisted structure analysis, story-lane swimlanes and an emotion curve. It runs entirely in the browser on your own machine, and the AI step is bring-your-own, not a hosted service.

**bkingfilm/lapian-notes** — AI 辅助的电影拉片工具：AI 拆出剧情泳道时间轴、结构树、情绪曲线，边播边写拉片笔记，免费开源全本地 | AI-assisted film breakdown notebook: story-lane timeline, structure tree, emotion curve. Free, open source, fully local.

- Repository: https://github.com/bkingfilm/lapian-notes
- Website: https://discord.gg/uT6xryBX9w
- Stars: 711 · Forks: 73
- Language: TypeScript
- License: MIT
- Published: 2026-09-17 · Updated: 2026-09-17 · Language: en
- Canonical page: https://hysenlabs.com/projects/bkingfilm-lapian-notes

## What Lapian Notes Solves for People Studying Film Narrative

Watching a film closely and writing down what happens, when, and why is slow manual work. Lapian Notes targets that specific job: it turns a film into an editable shot-by-shot study notebook. The README describes the output as a story-lane swimlane timeline, a structure tree and an audience-emotion curve, all generated from an AI analysis that the user runs. The intended user is a creator who wants to study cinematic narrative systematically, not a casual viewer. The tool is free, MIT-licensed and runs locally: the README states that the film and the notes are not uploaded to any server. That local-first design is the main reason to pick it over a web service that would need your video file.

## How the Pipeline Works: Frames, Subtitle, ZIP, JSON

The mechanism is a four-step wizard that stays at the top of the interface. After you import a film, the tool extracts one frame per second, producing a full-length timeline with screenshots. The README says a typical film yields 6000 to 8000 screenshots at that interval. It then reads embedded subtitles, or searches for subtitles online if none are embedded, and packages the screenshots and subtitles into a ZIP. That ZIP is the AI analysis package. You send it to any AI you like, paste the instruction that the tool has already copied to your clipboard, and upload the ZIP. When the AI returns a JSON file, you import it and the timeline, structure tree and emotion curve are generated. The design deliberately does not bind to one AI service and does not require an API key for the manual path. There is also a direct path, AI 直连分析, where you fill in your own API key once and the tool completes the analysis and imports the result automatically. The README lists presets for Gemini, Kimi, OpenAI and Claude, plus a custom option for any OpenAI-compatible endpoint. The key is stored only in the local browser, and token costs go to your own account. This direct path is only available in the full local version, not the online demo.

## Installing Lapian Notes and Running a First Analysis

The README gives a three-step path for people who do not program. Download the ZIP from the latest release page, specifically the `lapian-notes-vX.Y.Z.zip` asset rather than the source snapshot behind the Code button. Unzip it. Then start it: on Windows double-click `run.bat`, on Mac double-click `run.command`. On the first run the script prepares the runtime and program components, downloading a portable Node.js if none is installed, which the README says takes a few minutes. After that it opens in the browser. Keep the black service window open while you work. For developers, the requirements are Node.js 20.19+ or 22.12+ and a Chromium-based browser. The README gives these commands:

```bash
npm install
npm run dev
```

Open the address the terminal prints, which defaults to http://localhost:5173. ffmpeg is optional and only needed for automatic transcoding of formats such as RMVB, AVI and HEVC; H.264 MP4 does not need it. The README warns that automatic transcoding and automatic subtitle search are served by the dev server's local endpoints, so they require `npm run dev` or the startup script. In a static deployment built with `npm run build`, those two features degrade to manual operation and everything else still works. The test suite run by `npm run check` requires Node 22.18 or above because the test files are TypeScript passed to Node's built-in type stripping. The repository layout matches this description: `run.bat`, `run.command`, `setup.ps1`, `transcode-server-plugin.ts`, `subtitle-server-plugin.ts` and `ai-proxy-server-plugin.ts` sit at the top level alongside `src/` and `tests/`.

## The Free-AI Sampling Problem and Other Limits

The most useful warning in the README is about free AI tiers. A film at one frame per second produces 6000 to 8000 screenshots, and free quotas often cannot process that many. When the quota is insufficient, the README says the AI does not say so; it looks at a few frames from the beginning, middle and end and returns a thin result. You notice this after import as unusually few segments and very simple content. The suggested fix is to ask the AI to unpack the whole package and follow prompt.md segment by segment rather than sampling, or to switch to a paid tier or another AI. This is a real failure mode that is easy to mistake for a limitation of the tool. A second constraint is subtitle handling: the online trial version has no local transcoding and no automatic subtitle search, so those two need the full download. A third is storage. Notes are saved in browser localStorage and frame screenshots in IndexedDB. Because of browser security rules, the README states that after a refresh you must reselect the film file to extract frames again, though existing notes and screenshots are unaffected. The Save Project action exports a self-contained ZIP with notes, screenshots and Markdown for moving between browsers or backing up. Finally, the tool is the wrong choice if you want analysis without choosing a model: it is bring-your-own AI by design, and the quality of the output tracks the model you pick.

## Why There Is No DeepSeek Preset, and What That Says About the Design

Lapian Notes does not preset DeepSeek, and the README explains why in a way that reveals the tool's priorities. DeepSeek is a text-only model and cannot see images. The README argues that the core of film breakdown is visual: audiovisual technique, dialogue-free passages and the emotion curve all depend on looking at frames. Presetting a text-only model would let users run a degraded mode and conclude the tool is weak. If you want it anyway, the README says to choose the custom option, enter `https://api.deepseek.com`, and uncheck the option to include the frame montage, which falls back to subtitle-only analysis. That is described as adequate for dialogue-dense films. For AIs that cannot accept a ZIP, such as Kimi, Doubao, Tongyi and DeepSeek, the interface offers a no-archive version that exports the task description, subtitles and a montage of frames with timecodes as separate files, which you select and upload together. These choices point to a clear editorial position: the tool would rather degrade explicitly than silently.

## How Lapian Notes Differs from a General Video Annotation Tool

A general video annotation or timestamping tool records what you mark as you watch; it does not propose a structure. Lapian Notes inverts that by asking an AI to segment the film into story lines, group segments into a structure tree by main line, sub-line, emotional line and information line, and draw an audience-investment curve. The comparison is not with a competitor product but with the workflow of a spreadsheet plus a video player. What you gain is the swimlane timeline with reference cards for passages that reuse multiple lines, per-segment deep dives that package a single segment for a second AI pass down to scene and shot level, and player linkage where any timestamp in a segment, screenplay subsection or subtitle line jumps the player, with Play This Segment pausing automatically at the end. What you give up is any guarantee about the analysis: the segmentation quality depends entirely on the model you feed the ZIP to, and the README itself warns that a lazy model will return a shallow result. If you want deterministic, model-independent output, this is the wrong shape of tool.

## Licence, Maintenance and What Upgrades Cost You

The project is MIT-licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are included. That is a statement about the licence text, not legal advice for your situation. The repository is not archived, and the last push was on 2026-08-22, so the project has been touched within the last month. Release cadence has been steady: v0.5.0 on 2026-07-30 added faster frame extraction and an online demo, v0.5.1 on 2026-08-03 added direct AI analysis, and v0.5.2 on 2026-08-22 added black-frame detection and a subtitle length gate. The package version in package.json is 0.5.2, matching the latest release, so the repository head tracks the release. Upgrade cost is low for end users because the startup scripts fetch components automatically; developers pulling a new version should rerun `npm install` and be aware that the test suite requires Node 22.18 or above while development and build only require 20.19+ or 22.12+. The dependency list is small, with React 19, Vite 8 and html-to-image as the only runtime dependencies, which keeps the surface for breakage narrow.

## Conclusion

Adopt Lapian Notes if you want a structured, local notebook for studying narrative and you are willing to run the AI analysis yourself, either by pasting a ZIP into a chat model or by supplying your own API key. Skip it if you need a hosted service, a mobile app or a tool that does the analysis without you choosing a model and paying for tokens. Before committing, confirm that your film is H.264 MP4 or that ffmpeg is installed for transcoding, and check that your chosen AI can accept a 6000 to 8000 image package.

## FAQ

### Is Lapian Notes free and does it upload my film?

It is free and MIT-licensed, and the README states that the film and notes are not uploaded to any server. Notes are stored in browser localStorage and screenshots in IndexedDB.

### Do I need an API key to use Lapian Notes?

No. The default flow packages screenshots and subtitles into a ZIP that you send to any AI yourself, with no API key. The direct analysis path is optional and stores your key only in the local browser, with token costs on your own account.

### Why does my imported AI result have so few segments?

The README warns that a free AI tier may not process the 6000 to 8000 screenshots a film produces and will silently sample a few frames instead. Ask it to unpack the whole package and follow prompt.md without sampling, or switch to a paid tier or another model.

## Sources

- [bkingfilm/lapian-notes on GitHub](https://github.com/bkingfilm/lapian-notes)
- [License: MIT](https://github.com/bkingfilm/lapian-notes/blob/main/LICENSE)
- [Project website](https://discord.gg/uT6xryBX9w)
- [README](https://github.com/bkingfilm/lapian-notes/blob/main/README.md)
- [Releases](https://github.com/bkingfilm/lapian-notes/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/bkingfilm-lapian-notes