From 27980ad4e96f5483fd00cd5eff6c079ca00095d9 Mon Sep 17 00:00:00 2001 From: pgotta <168211683+pgotta@users.noreply.github.com> Date: Tue, 4 Aug 2026 15:36:14 -0400 Subject: [PATCH 1/6] Centralize Windows quick start in BUILD.md --- README.md | 38 +++++++++++++++++--------------------- 1 file changed, 17 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index a7244c7..9c67620 100644 --- a/README.md +++ b/README.md @@ -8,15 +8,11 @@ SeeStory opens as a desktop-style Windows app in a dedicated maximized Chrome or ![SeeStory desktop interface](screenshots/header.png) -## Windows quick start +## Quick start -1. Extract the complete SeeStory folder to a normal writable location. -2. Double-click **`install_all.bat`**. -3. Let the installer create the Python environment, install CUDA-enabled PyTorch, download and verify the required local image model, check ffmpeg, and create the desktop shortcut. -4. Choose whether to install the optional Photorealistic model when prompted. -5. Start SeeStory from the desktop shortcut or with **`run.bat`**. +See **[BUILD.md](BUILD.md)** for quick start, installation, launcher creation, model repair, manual shutdown, and diagnostic instructions. -Closing the dedicated SeeStory app window performs the same controlled shutdown as **`stop.bat`**. +Windows launcher files are intentionally excluded from the repository. `BUILD.md` is the source of truth for recreating them and explains which launcher to use for the initial setup. The downloadable release package includes the Windows launchers for convenience. Have these Parroty files ready: @@ -29,14 +25,14 @@ SeeStory also accepts EPUB, PDF, DOC, DOCX, TXT, Markdown, HTML, and RTF documen ## Requirements and disk space - Windows 10 or Windows 11. -- Python 3.12 for the Windows installer. -- An NVIDIA CUDA GPU. Installation stops if real CUDA execution cannot be proven. -- ffmpeg for motion clips and final video assembly. The installer checks for it and provides a clear error if it is missing. +- Python 3.12 for the Windows setup documented in `BUILD.md`. +- An NVIDIA CUDA GPU. Setup stops if real CUDA execution cannot be proven. +- ffmpeg for motion clips and final video assembly. The setup process checks for it and reports clearly when it is missing. - Enough free disk space for the Python environment, local model cache, and generated projects. The required DreamShaper XL Lightning model is roughly 7 GB. The optional RealVisXL Photorealistic model is a separate download of roughly similar size. The Python environment and CUDA libraries use several additional gigabytes, and long-book output folders can also grow to several gigabytes. -The installer does not permit a silent CPU fallback. The current release has been tested on Windows 11 with an RTX 5060 Laptop GPU with 8 GB of VRAM. +The setup process does not permit a silent CPU fallback. The current release has been tested on Windows 11 with an RTX 5060 Laptop GPU with 8 GB of VRAM. ## Local image generation @@ -44,8 +40,8 @@ SeeStory has one local image-generation path with automatic model routing. There - **DreamShaper XL Lightning** handles Cinematic, Storybook, Noir, Oil, Ink, and other illustrated styles. - **RealVisXL V5 Lightning** handles the Photorealistic style when that optional model was installed and GPU-tested. -- The installer owns all large model downloads. The running app is cache-only and cannot silently begin a multi-gigabyte model transfer. -- Missing or incomplete models produce an immediate instruction to rerun the installer. +- The setup process documented in `BUILD.md` owns all large model downloads. The running app is cache-only and cannot silently begin a multi-gigabyte model transfer. +- Missing or incomplete models produce an immediate repair message. Follow the model-repair instructions in `BUILD.md`. - Prompt construction includes scene-coherence, anatomy, duplicate-person, malformed-face, extra-limb, extra-finger, watermark, and accidental-text suppression. - Lower-VRAM systems can use model CPU offload and smaller retry resolutions after a CUDA out-of-memory error. - Model weights are not included in this repository or release package and remain subject to their upstream licenses. @@ -58,7 +54,7 @@ Choose the art style, optional custom visual treatment, words per page, pages pe ![Photorealistic setup and sample](screenshots/setup-photoreal.png) -The optional Photorealistic model must be selected during `install_all.bat`. If it was not installed, rerun the installer or use `install_stable_diffusion.bat` to add and verify it. +The optional Photorealistic model must be added and GPU-tested during Windows setup. See `BUILD.md` for the setup and model-repair instructions. ![Storybook watercolor example](screenshots/style-storybook.png) @@ -113,7 +109,7 @@ This is controlled Ken Burns-style movement on still images, not generative vide - Tracks the dedicated app process and uses a heartbeat fallback for clean shutdown. - Writes launcher, server, lifecycle, installation, and diagnostic information under `logs/`. -If closing the app window ever leaves SeeStory running, run **`shutdown_diagnostic.bat`** before manually ending the process. It creates a timestamped report containing listener, PID, session, GPU, and recent-log information. +Closing the app window normally stops SeeStory automatically. `BUILD.md` documents the explicit stop and shutdown-diagnostic procedures for the uncommon case where a process remains running. ## Output @@ -128,10 +124,10 @@ Each project folder under `output/` can contain: ## Troubleshooting -- **The app does not open:** Run `shutdown_diagnostic.bat` and check `logs\launcher.log` and `logs\seestory.log`. -- **ffmpeg is missing:** Install ffmpeg, restart Windows or the terminal session if needed, and rerun the installer. -- **The model is missing or incomplete:** Rerun `install_all.bat` or `install_stable_diffusion.bat`. The desktop runtime will not download the model itself. -- **CUDA is unavailable:** Update the NVIDIA driver and rerun the installer. SeeStory will not silently use the CPU. +- **The app does not open:** Follow the shutdown-diagnostic procedure in `BUILD.md`, then check `logs\launcher.log` and `logs\seestory.log`. +- **ffmpeg is missing:** Follow the setup instructions in `BUILD.md`, then restart Windows or the terminal session if needed. +- **The model is missing or incomplete:** Follow the model-repair instructions in `BUILD.md`. The desktop runtime will not download model weights itself. +- **CUDA is unavailable:** Update the NVIDIA driver and repeat the GPU verification described in `BUILD.md`. SeeStory will not silently use the CPU. - **Out of VRAM:** Close other GPU-heavy programs. SeeStory can retry smaller generation sizes and use model CPU offload, but available VRAM still limits practical resolution. - **Garbled text appears in images:** Remove titles, author names, genre terms, and "book cover" wording from the custom-style field. - **Repeated scenes in an old project:** Rebuild the storyboard from the original ebook so the current nonduplicating parser and scene-selection logic can be applied. @@ -139,9 +135,9 @@ Each project folder under `output/` can contain: ## Repository and Windows launcher rules -Windows `.bat`, `.cmd`, and `.lnk` files are intentionally excluded from git. The downloadable release package includes the BAT launchers, while **[BUILD.md](BUILD.md)** contains their exact contents so they can be recreated from a repository clone. +Windows `.bat`, `.cmd`, and `.lnk` files are intentionally excluded from git. This README deliberately does not duplicate executable launcher commands. See **[BUILD.md](BUILD.md)** for the quick start instructions and the exact contents of every Windows launcher. -The repository also excludes virtual environments, runtime state, logs, generated output, uploads, shortcuts, local models, and model caches. +The downloadable release package includes the launcher files for convenience. The repository also excludes virtual environments, runtime state, logs, generated output, uploads, shortcuts, local models, and model caches. See **[CHANGELOG.md](CHANGELOG.md)** for the complete release history, fixes, validation summary, and upgrade notes. From 3b26318940a0fa0707505ff47ab494ac19cd17e8 Mon Sep 17 00:00:00 2001 From: pgotta <168211683+pgotta@users.noreply.github.com> Date: Tue, 4 Aug 2026 15:36:42 -0400 Subject: [PATCH 2/6] Temporarily add BUILD.md documentation updater --- .github/workflows/docs-build-quickstart.yml | 58 +++++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 .github/workflows/docs-build-quickstart.yml diff --git a/.github/workflows/docs-build-quickstart.yml b/.github/workflows/docs-build-quickstart.yml new file mode 100644 index 0000000..c5468e6 --- /dev/null +++ b/.github/workflows/docs-build-quickstart.yml @@ -0,0 +1,58 @@ +name: Update BUILD quick start + +on: + push: + branches: + - docs/centralize-quick-start + +permissions: + contents: write + +jobs: + update-build-doc: + if: github.actor != 'github-actions[bot]' + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + ref: docs/centralize-quick-start + - name: Add explicit quick start to BUILD.md + shell: bash + run: | + python - <<'PY' + from pathlib import Path + + path = Path('BUILD.md') + text = path.read_text(encoding='utf-8') + if '## Quick start\n' not in text: + intro = ( + 'This document is the source of truth for rebuilding the Windows helper files that are intentionally excluded from git. ' + 'The release/test ZIP may contain these BAT files for convenience, but the repository keeps `*.bat`, `*.cmd`, and `*.lnk` ignored.\n\n' + ) + quick = ( + '## Quick start\n\n' + 'The GitHub repository intentionally does not include executable Windows launcher files. Use the downloadable release package, ' + 'or recreate the required launchers from the exact code blocks in this document.\n\n' + '1. Place the complete SeeStory project in a normal writable folder.\n' + '2. Run **`install_all.bat`**. This is the supported first-time setup entry point. It creates the Python environment, installs and verifies CUDA, checks ffmpeg, downloads and GPU-tests the required local model, optionally installs the Photorealistic model, and creates the desktop shortcut.\n' + '3. After setup completes, start SeeStory from the desktop shortcut or with **`run.bat`**.\n' + '4. Close the dedicated SeeStory window to stop the background service. Use **`stop.bat`** only when an explicit manual stop is needed.\n\n' + 'For non-interactive setup, `install_all.bat default` installs only the required illustration model, while `install_all.bat all` installs both the illustration and Photorealistic models.\n\n' + ) + if intro not in text: + raise SystemExit('BUILD.md introduction changed; refusing an unsafe insertion') + text = text.replace(intro, intro + quick, 1) + path.write_text(text, encoding='utf-8', newline='\n') + PY + - name: Commit BUILD.md update + shell: bash + run: | + if git diff --quiet -- BUILD.md; then + echo "BUILD.md already contains the quick start section." + exit 0 + fi + git config user.name "github-actions[bot]" + git config user.email "41898282+github-actions[bot]@users.noreply.github.com" + git add BUILD.md + git commit -m "Add explicit BUILD quick start" + git push origin HEAD:docs/centralize-quick-start From 2cb666e293987f249ab205cbd5b69f1ba48dceac Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Tue, 4 Aug 2026 19:37:01 +0000 Subject: [PATCH 3/6] Add explicit BUILD quick start --- BUILD.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/BUILD.md b/BUILD.md index e6078f0..8288398 100644 --- a/BUILD.md +++ b/BUILD.md @@ -2,6 +2,17 @@ This document is the source of truth for rebuilding the Windows helper files that are intentionally excluded from git. The release/test ZIP may contain these BAT files for convenience, but the repository keeps `*.bat`, `*.cmd`, and `*.lnk` ignored. +## Quick start + +The GitHub repository intentionally does not include executable Windows launcher files. Use the downloadable release package, or recreate the required launchers from the exact code blocks in this document. + +1. Place the complete SeeStory project in a normal writable folder. +2. Run **`install_all.bat`**. This is the supported first-time setup entry point. It creates the Python environment, installs and verifies CUDA, checks ffmpeg, downloads and GPU-tests the required local model, optionally installs the Photorealistic model, and creates the desktop shortcut. +3. After setup completes, start SeeStory from the desktop shortcut or with **`run.bat`**. +4. Close the dedicated SeeStory window to stop the background service. Use **`stop.bat`** only when an explicit manual stop is needed. + +For non-interactive setup, `install_all.bat default` installs only the required illustration model, while `install_all.bat all` installs both the illustration and Photorealistic models. + ## Build/runtime layout - `launch_seestory.pyw` — hidden desktop launcher. Starts Flask with `pythonw.exe`, waits for readiness, opens the tracked Chrome/Edge app window, and shuts the server down when that window closes. From 7be87afd3c8f3a9ff67c8ab8ef99f3156398c32a Mon Sep 17 00:00:00 2001 From: pgotta <168211683+pgotta@users.noreply.github.com> Date: Tue, 4 Aug 2026 15:37:05 -0400 Subject: [PATCH 4/6] Trigger BUILD.md quick start update --- .docs-update-trigger | 1 + 1 file changed, 1 insertion(+) create mode 100644 .docs-update-trigger diff --git a/.docs-update-trigger b/.docs-update-trigger new file mode 100644 index 0000000..27ab4b1 --- /dev/null +++ b/.docs-update-trigger @@ -0,0 +1 @@ +Update BUILD.md quick start documentation. From 721a38b83f0814043855b46d8eaa36417048ca0d Mon Sep 17 00:00:00 2001 From: pgotta <168211683+pgotta@users.noreply.github.com> Date: Tue, 4 Aug 2026 15:37:30 -0400 Subject: [PATCH 5/6] Remove temporary documentation trigger --- .docs-update-trigger | 1 - 1 file changed, 1 deletion(-) delete mode 100644 .docs-update-trigger diff --git a/.docs-update-trigger b/.docs-update-trigger deleted file mode 100644 index 27ab4b1..0000000 --- a/.docs-update-trigger +++ /dev/null @@ -1 +0,0 @@ -Update BUILD.md quick start documentation. From 7582a4fc7458db433ce4bcc36ccd0ef05b0b1393 Mon Sep 17 00:00:00 2001 From: pgotta <168211683+pgotta@users.noreply.github.com> Date: Tue, 4 Aug 2026 15:37:37 -0400 Subject: [PATCH 6/6] Remove temporary documentation updater --- .github/workflows/docs-build-quickstart.yml | 58 --------------------- 1 file changed, 58 deletions(-) delete mode 100644 .github/workflows/docs-build-quickstart.yml diff --git a/.github/workflows/docs-build-quickstart.yml b/.github/workflows/docs-build-quickstart.yml deleted file mode 100644 index c5468e6..0000000 --- a/.github/workflows/docs-build-quickstart.yml +++ /dev/null @@ -1,58 +0,0 @@ -name: Update BUILD quick start - -on: - push: - branches: - - docs/centralize-quick-start - -permissions: - contents: write - -jobs: - update-build-doc: - if: github.actor != 'github-actions[bot]' - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - with: - ref: docs/centralize-quick-start - - name: Add explicit quick start to BUILD.md - shell: bash - run: | - python - <<'PY' - from pathlib import Path - - path = Path('BUILD.md') - text = path.read_text(encoding='utf-8') - if '## Quick start\n' not in text: - intro = ( - 'This document is the source of truth for rebuilding the Windows helper files that are intentionally excluded from git. ' - 'The release/test ZIP may contain these BAT files for convenience, but the repository keeps `*.bat`, `*.cmd`, and `*.lnk` ignored.\n\n' - ) - quick = ( - '## Quick start\n\n' - 'The GitHub repository intentionally does not include executable Windows launcher files. Use the downloadable release package, ' - 'or recreate the required launchers from the exact code blocks in this document.\n\n' - '1. Place the complete SeeStory project in a normal writable folder.\n' - '2. Run **`install_all.bat`**. This is the supported first-time setup entry point. It creates the Python environment, installs and verifies CUDA, checks ffmpeg, downloads and GPU-tests the required local model, optionally installs the Photorealistic model, and creates the desktop shortcut.\n' - '3. After setup completes, start SeeStory from the desktop shortcut or with **`run.bat`**.\n' - '4. Close the dedicated SeeStory window to stop the background service. Use **`stop.bat`** only when an explicit manual stop is needed.\n\n' - 'For non-interactive setup, `install_all.bat default` installs only the required illustration model, while `install_all.bat all` installs both the illustration and Photorealistic models.\n\n' - ) - if intro not in text: - raise SystemExit('BUILD.md introduction changed; refusing an unsafe insertion') - text = text.replace(intro, intro + quick, 1) - path.write_text(text, encoding='utf-8', newline='\n') - PY - - name: Commit BUILD.md update - shell: bash - run: | - if git diff --quiet -- BUILD.md; then - echo "BUILD.md already contains the quick start section." - exit 0 - fi - git config user.name "github-actions[bot]" - git config user.email "41898282+github-actions[bot]@users.noreply.github.com" - git add BUILD.md - git commit -m "Add explicit BUILD quick start" - git push origin HEAD:docs/centralize-quick-start