diff --git a/README.md b/README.md index da79453..3f2220e 100644 --- a/README.md +++ b/README.md @@ -4,61 +4,60 @@ ScriptCut

-> 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 -``` +

+ Download for macOS — Apple Silicon + Release notes & verification +

-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. @@ -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. diff --git a/docs/FIRST_EXPORT.md b/docs/FIRST_EXPORT.md index c8d0cc2..52bafb6 100644 --- a/docs/FIRST_EXPORT.md +++ b/docs/FIRST_EXPORT.md @@ -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 @@ -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. diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md index 062873d..bc4054d 100644 --- a/docs/USER_GUIDE.md +++ b/docs/USER_GUIDE.md @@ -4,58 +4,72 @@ This guide is for creators using the ScriptCut desktop app. ## What ScriptCut Does -ScriptCut lets you edit spoken video by editing the transcript. Delete words to cut the video, review playback, package shorts, and export social-ready files from your own computer. +ScriptCut lets you edit spoken video by editing the transcript. Delete words to cut the video, review playback, create social-ready clips, and export files from your own computer. ## Install the App -1. Go to the official [ScriptCut Releases feed](https://github.com/FernandoAbishai/ScriptCut/releases) and choose a prerelease explicitly identified as self-contained for macOS Apple Silicon. -2. Download that tagged macOS Apple Silicon (arm64) `.dmg`. -3. Open the DMG and launch ScriptCut. -4. If macOS blocks the ad-hoc-signed first launch, use **System Settings → Privacy & Security → Open Anyway** after confirming the download came from the official Releases feed. +1. Use a macOS Apple Silicon Mac (M1 or newer). +2. [Download the official v0.1.0-alpha.5 Apple Silicon DMG](https://github.com/FernandoAbishai/ScriptCut/releases/download/v0.1.0-alpha.5/ScriptCut-v0.1.0-alpha.5-arm64.dmg). +3. Open the DMG and move ScriptCut to Applications. +4. Launch ScriptCut. If macOS blocks the first launch, use **System Settings → Privacy & Security → Open Anyway** after confirming you downloaded the official file. -The supported self-contained public-alpha path bundles portable Python, the pinned core runtime, FFmpeg, and FFprobe. ScriptCut downloads and verifies the baseline transcription model on first use; creators do not install system Python or FFmpeg for a qualifying packaged app. Older alpha releases may predate this path; check the individual release notes and manifest. If there is no qualifying public release yet, use the repository setup in [Install ScriptCut](./INSTALL.md). +The supported self-contained public-alpha path includes the application runtime, Python runtime, core dependencies, FFmpeg, and FFprobe. The published v0.1.0-alpha.5 installer is for macOS Apple Silicon / arm64, is ad-hoc signed, and is not notarized. Older alpha releases may predate this self-contained path; check their release notes before using an older build. ScriptCut downloads and verifies the baseline transcription model on first transcription, then can reuse that verified local model. ## First Launch -ScriptCut checks the packaged baseline readiness before you edit: +Choose one of the current Home actions: -- Desktop app access for opening and saving local files. -- Local backend for transcription and exports. -- Bundled Python runtime for the backend. -- Bundled FFmpeg for video export. -- Transcription engine availability. +- **Edit a Video** — Edit spoken video by editing the transcript. +- **Create Clips** — Find, review and export social-ready moments. +- **Open Project** — Reopen an existing ScriptCut project. -Green checks mean the core workflow is ready. Background removal is optional. +ScriptCut checks the packaged baseline readiness before you edit. Green checks mean the core workflow is ready; background removal is optional. An AI provider is not required for core transcript editing or export. ## Make Your First Edit -1. Click **Open Video File**. +1. From Home, click **Edit a Video**. 2. Choose a video or audio file. 3. Wait for transcription to finish. 4. Select words in the transcript. 5. Press Delete to cut selected words from the edit. 6. Press Space to preview playback. -7. Open **Export**. -8. Choose a creator template such as **Shorts Batch**, **Caption Review**, or **Podcast Clip**. -9. Click **Export**. -10. Use **Reveal in Finder** or **Open** to find the finished file. +7. Open **Export**, review the preflight, and click **Export**. +8. Use **Reveal in Finder** or **Open file** to find the finished file. -## Make Shorts +## Create Clips -1. Open the **AI** panel. -2. Open the **Clips** tab. -3. Click **Find Best Clips**. -4. Draft the suggestions you want to review. -5. Adjust the in/out times. -6. Package metadata for hook, title, caption, description, hashtags, and hook frames. -7. Use the readiness score to fix missing captions, metadata, or export settings. -8. Export one draft or use **Export Approved** for a batch. +Create Clips follows **Find → Review → Prepare → Export**. -AI helps find and package clips, but exporting still uses the local media and local backend. +### Find + +1. From Home, click **Create Clips**. +2. Choose a local video file and wait for transcription. +3. In the **Find** stage, click **Find moments with AI**, or select transcript words and choose **Draft clip** yourself. Manual clips do not require an AI provider. + +### Review + +Use **Preview** for each suggested moment. Choose **Approve** for moments worth preparing or **Skip** for moments you do not want. When the review is complete, choose **Prepare approved clips**. + +### Prepare + +For each clip, use the current controls to: + +- adjust the **In** and **Out** range; +- choose the **Frame** and adjust **Reframe** when using a social aspect ratio; +- use **Preview**; +- choose **Captions** and a caption **Style**; +- optionally open **Publishing copy — optional** for hook, description, caption, hashtags, or title suggestions; +- optionally open **Advanced export settings** for **Resolution**, **Format**, **Enhance audio**, or **Background removal**. + +Publishing copy is optional and is not required to export the clip. + +### Export + +Choose **Export** when the clip is ready. The result shows **Clip ready** and the output file. In the desktop app, choose **Reveal in Finder** to locate the video. If burn-in captions are unavailable, the result can include a matching `.srt` sidecar. ## Save Projects -Use **Save Project** to create a `.scriptcut` project file. Project files preserve transcript edits, clip drafts, settings, and package metadata. +Use **Save Project** to create a `.scriptcut` project file. Project files preserve transcript edits, clip drafts, settings, and optional publishing copy. ScriptCut also uses desktop autosave when available, so interrupted work can be recovered the next time the same media is opened. @@ -65,10 +79,6 @@ The browser page at `localhost:5173` is for development and quick testing. Use t ## Common Fixes -If export is unavailable in a desktop release, choose the intended prerelease from the official Releases feed and run the first-launch checks again. If you run from source, install FFmpeg or run `npm run release:ffmpeg` before packaging. - -If transcription is unavailable, choose Auto or Whisper fallback, or install the optional Parakeet dependencies shown by the first-run setup assistant. - -If AI actions do nothing, open Settings and choose a configured AI provider. Ollama can run locally; cloud providers require API keys. +If transcription is unavailable, wait for the baseline model preparation to finish and check the first-launch readiness messages. If AI discovery does nothing, check that an AI provider is configured; local Ollama and configured cloud providers are optional helpers, not requirements for manual transcript editing or manual clip drafting. For more details, see [Troubleshooting](./TROUBLESHOOTING.md).