Skip to content

docs: simplify alpha.5 download and onboarding #53

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
FernandoAbishai merged 2 commits into from
Aug 25, 2026
+97 −83
Merged

docs: simplify alpha.5 download and onboarding #53

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a8df3a0
docs: simplify alpha.5 download and onboarding
FernandoAbishai Aug 25, 2026
6134f59
docs: preserve alpha release guidance
FernandoAbishai Aug 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 36 additions & 31 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,61 +4,60 @@
<img src="frontend/public/brand/scriptcut-wordmark.svg" width="360" alt="ScriptCut" />
</p>

> Edit videos like documents. Turn long-form recordings into polished videos and social clips, locally on your machine.
> Edit spoken video like a document. Turn long recordings into finished videos and social-ready clips.

ScriptCut is an open-source, local-first desktop video production tool for YouTube creators, podcasters, educators, founders, interview creators, streamers, and anyone repurposing spoken recordings.

Its creator workflow is simple:
## Download ScriptCut

```text
Choose a video → edit the transcript → review → export
```
<p>
<a href="https://github.com/FernandoAbishai/ScriptCut/releases/download/v0.1.0-alpha.5/ScriptCut-v0.1.0-alpha.5-arm64.dmg"><img src="https://img.shields.io/badge/Download%20for%20macOS%20%E2%80%94%20Apple%20Silicon-2f81f7?style=for-the-badge" alt="Download for macOS — Apple Silicon" /></a>
<a href="https://github.com/FernandoAbishai/ScriptCut/releases/tag/v0.1.0-alpha.5">Release notes &amp; verification</a>
</p>

ScriptCut is different from a cloud-first editor because local processing is the default path, AI helpers are optional, and project files stay creator-owned. The current product is a desktop alpha: it already supports the core editing and export workflow, while installation and platform support continue to mature.
**v0.1.0-alpha.5 · macOS Apple Silicon / arm64 · Public alpha · ad-hoc signed · not notarized**

See [the Product Vision](docs/PRODUCT_VISION.md) for the canonical product direction.
No Terminal setup is required for the supported packaged app. This public download is for Apple Silicon Macs; it is not a universal macOS, Windows, or Linux installer.

![ScriptCut export workspace with edited preview, transcript, timeline, export preflight, output presets, and caption delivery](docs/assets/scriptcut-alpha4-export.png)
## Install in 3 steps

## Start Here
1. Download the official DMG above.
2. Open it and move **ScriptCut** to **Applications**.
3. Launch **ScriptCut** from Applications.

The intended creator path is the **ScriptCut desktop app**:
If macOS blocks the first launch, open **System Settings → Privacy & Security → Open Anyway**, then confirm the prompt. Use this only for the official ScriptCut download linked above. Do not disable Gatekeeper or run Terminal quarantine commands.

1. [Download ScriptCut v0.1.0-alpha.4 for macOS Apple Silicon](https://github.com/FernandoAbishai/ScriptCut/releases/download/v0.1.0-alpha.4/ScriptCut-v0.1.0-alpha.4-arm64.dmg).
2. Open the DMG and install ScriptCut.
3. If macOS blocks the first launch, use **System Settings → Privacy & Security → Open Anyway**, then confirm the prompt.
4. Choose **Edit a Video** or **Create Clips**, then select local media.
5. Review the transcript and export when the preflight panel is ready.
For a short, non-technical walkthrough, read the [First Export Guide](docs/FIRST_EXPORT.md).

For release notes, checksums, the manifest, and attestations, see the [v0.1.0-alpha.4 release page](https://github.com/FernandoAbishai/ScriptCut/releases/tag/v0.1.0-alpha.4).
## What to expect on first use

For a short, non-technical walkthrough, read the [First Export Guide](docs/FIRST_EXPORT.md).
The supported self-contained public-alpha path includes the application runtime, Python runtime, core dependencies, FFmpeg, and FFprobe. No separate Python or FFmpeg setup is required for this packaged release. Older alpha releases may predate this self-contained path; check their release notes before downloading an older build.

If a release asset is not available, ScriptCut can be run from source using the contributor setup below. The complete release process is documented in [docs/RELEASE.md](docs/RELEASE.md).
Before the first transcription, ScriptCut downloads and verifies the baseline transcription model. Later baseline transcriptions can reuse that verified local model. An AI provider is not required for core transcript editing or export.

## The two primary workflows
## What ScriptCut does

### Edit a Video
ScriptCut is different from a cloud-first editor because local processing is the baseline path, AI helpers are optional, and project files stay creator-owned. Choose a recording, edit the words, review the result, and export a finished video or clip.

Open a video or audio file, transcribe it locally, edit the word-level transcript, preview the result, and export. You can delete, restore, mute, or hide selected words from captions. AI edit plans and filler-word suggestions are reviewable helpers; they do not replace editorial approval.
See [the Product Vision](docs/PRODUCT_VISION.md) for the canonical product direction.

See [docs/USER_GUIDE.md](docs/USER_GUIDE.md) for the detailed creator walkthrough.
![ScriptCut export workspace with edited preview, transcript, timeline, export preflight, output presets, and caption delivery](docs/assets/scriptcut-alpha4-export.png)

### Create Clips
## The two primary workflows

Open a long-form recording, find or create candidate moments, review and trim drafts, package metadata and hook-frame notes, then export approved clips. The current app supports AI clip suggestions, editable drafts, social metadata, vertical/square output, captions, readiness checks, and batch export. Discovery and packaging still depend on review, local setup, and—when selected—an available AI provider.
### Edit a Video

## Self-contained public-alpha path
**Edit spoken video by editing the transcript.** Open a local video or audio file, edit the transcript, preview the result, and export. You can delete, restore, mute, or hide selected words from captions. AI edit plans and filler-word suggestions are reviewable helpers; they do not replace your decisions.

ScriptCut's supported self-contained public-alpha path is **macOS Apple Silicon (arm64)**. Public alphas produced by the current release pipeline bundle the application runtime, portable Python, the core runtime pack, FFmpeg/FFprobe, and baseline Whisper transcription code. System Python and backend dependency installation are not required for that packaged baseline path.
See [docs/USER_GUIDE.md](docs/USER_GUIDE.md) for the detailed creator walkthrough.

The trusted baseline model is downloaded and verified into app-managed storage on first transcription. Subsequent baseline transcription can reuse the verified local model without model-network access. A qualifying public alpha uses an ad-hoc code signature for package integrity, but is not signed with Apple Developer ID or notarized by Apple, so macOS first launch may require **System Settings → Privacy & Security → Open Anyway**. Use that approval only for a DMG downloaded from the official ScriptCut Releases page. Older alpha releases may predate this self-contained runtime; check each release's notes and manifest before downloading.
### Create Clips

See [Platform Support](docs/PLATFORM_SUPPORT.md) for the current support matrix. macOS Intel preparation is available for maintainers, while Windows and Linux are source-development paths rather than verified public installers. The browser page at `localhost:5173` is for development and testing; it does not provide the desktop app’s native file access or the same autosave workflow.
**Find, review and export social-ready moments.** The current lifecycle is **Find → Review → Prepare → Export**. Find moments with AI when a provider is configured, or select transcript words yourself and choose **Draft clip**; manual clips can move directly into **Prepare**.

In browser mode, media is uploaded to the local backend for transcription and export, and finished files are offered as downloads. Use the desktop app for native file access, persistent export folders, autosave, and Finder reveal actions.
In **Prepare**, trim the range, preview the clip, adjust framing/reframe, and choose captions. **Advanced export settings** such as resolution, format, enhance audio, and background removal are secondary controls. **Publishing copy is optional** and is not required to export. A successful export shows a creator-facing **Clip ready** result; when burn-in captions are unavailable, captions can be delivered as a matching `.srt` sidecar.

## What is available today
## What works today

- Word-level transcription through Parakeet TDT v3, WhisperX, or Whisper when the selected local engine is installed.
- Transcript-based editing with edited playback, undo/redo, waveform/timeline synchronization, and speaker-aware operations when speaker labels are available.
Expand All @@ -76,7 +75,13 @@ The desktop app runs an Electron shell with a local React interface, a local Fas

AI features can use local Ollama or configured OpenAI, Claude, or 9Router providers. Selecting an external provider can send the requested transcript or prompt context to that provider. ScriptCut does not require AI for core transcript editing or export, and this README does not make a blanket privacy claim beyond the configured workflow.

## Contributor quick start
See [Platform Support](docs/PLATFORM_SUPPORT.md) for the support matrix. Browser mode at `localhost:5173` is for development and testing; use the desktop app for native file access, persistent export folders, autosave, and Finder reveal actions.

## For developers and contributors

If a public release asset is not available, ScriptCut can be run from source using the contributor setup below. The complete release process is documented in [docs/RELEASE.md](docs/RELEASE.md).

### Contributor quick start

These steps are for running ScriptCut from the repository.

Expand Down
35 changes: 17 additions & 18 deletions docs/FIRST_EXPORT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,15 @@
# Your First ScriptCut Export with v0.1.0-alpha.4
# Your First ScriptCut Export with v0.1.0-alpha.5

This guide matches the verified v0.1.0-alpha.4 ScriptCut desktop alpha. It is for creators using the packaged app, not contributors building from source.
This guide is for creators using the packaged ScriptCut desktop alpha. It does not require GitHub or developer tools.

## Before You Start

- Use a macOS Apple Silicon Mac (M1 or newer).
- [Download ScriptCut-v0.1.0-alpha.4-arm64.dmg](https://github.com/FernandoAbishai/ScriptCut/releases/download/v0.1.0-alpha.4/ScriptCut-v0.1.0-alpha.4-arm64.dmg), then open the DMG and install ScriptCut.
- For release notes, checksums, the manifest, and attestations, see the [v0.1.0-alpha.4 release page](https://github.com/FernandoAbishai/ScriptCut/releases/tag/v0.1.0-alpha.4).
- [Download ScriptCut-v0.1.0-alpha.5-arm64.dmg](https://github.com/FernandoAbishai/ScriptCut/releases/download/v0.1.0-alpha.5/ScriptCut-v0.1.0-alpha.5-arm64.dmg), open the DMG, and move ScriptCut to Applications.
- For release notes and verification, see the [v0.1.0-alpha.5 release page](https://github.com/FernandoAbishai/ScriptCut/releases/tag/v0.1.0-alpha.5).
- If macOS blocks the first launch, use **System Settings → Privacy & Security → Open Anyway** for the official download.

A qualifying public alpha bundles portable Python, the pinned core runtime, FFmpeg, and FFprobe for the supported baseline path. On the first transcription, ScriptCut downloads and verifies the baseline model with progress, then stores it in app-managed local storage for later offline reuse. No system Python or separate FFmpeg installation is required for this packaged release. Older alpha releases may predate this self-contained path.
The supported self-contained public-alpha path includes the application runtime, Python runtime, core dependencies, FFmpeg, and FFprobe. No separate Python or FFmpeg setup is required for this supported packaged release. Older alpha releases may predate this self-contained path; check their release notes before using an older build. Before the first transcription, ScriptCut downloads and verifies the baseline transcription model; later baseline transcriptions can reuse that verified local model. An AI provider is not required for core transcript editing or export.

## Edit a Video

Expand All @@ -19,26 +19,25 @@ A qualifying public alpha bundles portable Python, the pinned core runtime, FFmp
4. Select unwanted words and press Delete.
5. Press Space to preview the edited playback.
6. Open **Export**.
7. Check the compact export preflight. It should show a source, destination, renderer, and caption delivery method.
8. Click **Export**, then use **Reveal in Finder** when it completes.
7. Check the export preflight, then click **Export**.
8. When it completes, use **Reveal in Finder** to find the finished file.

## Create Clips

1. Click **Create Clips**.
2. Choose a local video file and wait for transcription and any required model preparation to finish. ScriptCut opens the Create Clips workspace after transcription.
3. Find moments with AI, or select transcript words and choose **Draft clip** yourself. An AI provider is optional for manual drafting.
4. Review the draft, trim it, and set its frame and captions.
5. Approve the prepared clip.
6. Export the approved draft. Batch export only runs approved drafts, so one failed clip does not stop the rest.
2. Choose a local video file and wait for transcription and any required model preparation to finish.
3. In **Find**, click **Find moments with AI**, or select transcript words yourself and choose **Draft clip**. Manual clips can move directly into **Prepare**; an AI provider is optional for manual drafting.
4. In **Review**, use **Preview**, then **Approve** the AI suggestions worth preparing. Select **Prepare approved clips** when the review is complete.
5. In **Prepare**, adjust the clip range, use **Preview**, choose the frame/reframe, and choose captions. **Publishing copy — optional** is not required to export.
6. Use **Advanced export settings** only when needed for resolution, format, enhance audio, or background removal.
7. Click **Export**. A successful result is shown as **Clip ready**; in the desktop app, use **Reveal in Finder** to locate it.

## Captions

ScriptCut checks caption support before export. When burn-in captions are available, they are rendered directly into the video. When the packaged FFmpeg build cannot render them, ScriptCut exports the video plus a matching `.srt` caption file. The export preflight tells you which result you will get before you start, including **Video + .srt sidecar** when that fallback applies.
ScriptCut checks caption support before export. When burn-in captions are available, they are rendered directly into the video. When burn-in is unavailable, ScriptCut can export the video plus a matching `.srt` caption sidecar. The export result and preflight show which result you will get.

## When Export Is Blocked

1. Read the Export preflight message first. It identifies whether the source, destination, renderer, or caption setting needs attention.
2. Open **Settings** and choose **Copy report** to create a redacted support report.
3. Open **Bug form**, paste the report, and include the steps that caused the problem and a screenshot when useful.

The report removes local file paths and credential-like values before it is copied.
1. Read the export preflight or readiness message first. It identifies what needs attention.
2. Adjust the source, clip range, destination, or selected export option it names.
3. Retry the export. If the issue continues, use **Settings → Copy report** to create a redacted support report.
Loading