# Eightfold V2: complete local-app build prompt

Copy the entire prompt below into a coding assistant that can create files, install dependencies and run programs on your own computer. Give it a new, empty project folder. This is a reconstruction specification for the current Eightfold V2, not its source code or a copy of its music assets. Different local AI runs can produce different wording, passage choices and original compositions.

The original implementation runs on an Apple Silicon Mac. This prompt asks the builder to inspect the recipient's computer and adapt the runtime when necessary. Windows, Linux and Intel Mac implementations need their own testing; they are not already verified ports.

---

## BEGIN BUILD PROMPT

Build me a complete, working local desktop application called **Eightfold V2**. Implement, run, test and package it on this computer. Do not stop at a plan, a design mockup, a static interface or partially connected buttons.

The app turns a long recording into up to eight editable social video cards. Every card starts as a text-and-portrait video. It can optionally become a short excerpt of the original recording, with original speech, captions and optional music. It must work locally without a required paid AI API, cloud rendering service or music subscription.

Follow all requirements below. They describe the intended finished product, including fixes learned while developing the original. Preserve these behaviours when choosing implementation details.

### 1. Inspect this computer and establish the local architecture

First inspect the operating system, processor architecture, available RAM, graphics hardware, free storage and existing development tools. Work in the folder supplied for this project. Never copy a previous developer's username, absolute paths, hardware identifiers or example source videos into my build.

If an earlier Eightfold or another application already exists, create a separate installation with its own application identity, runtime, models, project data, caches and export registry. Do not modify the earlier installation. Avoid shared writable files or symlinks into another version. Do not delete unrelated software, media or models.

The reference machine was an Apple M2 Pro Mac mini with 16 GB memory. Optimise sensibly for that class of hardware, but detect what is actually available here. Report material hardware limits honestly.

For Apple Silicon, use this proven architecture unless there is a concrete compatibility reason to adapt it:

- A native macOS application launcher using Swift, AppKit and WKWebView.
- A Python backend in a project-specific virtual environment.
- A polished HTML, CSS and JavaScript interface served over loopback.
- FFmpeg and ffprobe for media inspection, conversion, mixing and rendering.
- Pillow and NumPy, or an equivalent local graphics implementation, for deterministic text and backgrounds.
- MLX/Metal for local language-model inference and local Whisper transcription.
- Native macOS Vision face detection for portrait suggestions.
- Native directory selection through an application-owned NSOpenPanel.

On Windows, Linux or Intel Macs, implement equivalent local behaviour with an appropriate desktop wrapper and native dialogs. Evaluate a compatible quantised language model through llama.cpp and local transcription through whisper.cpp or another verified local runtime. These are adaptation options, not claims of identical speed or identical output. Choose one suitable implementation for this computer, rather than installing every runtime.

Use current official documentation to verify installation commands, compatibility, model availability and licences. Pin the versions and model revisions that actually work. Do not invent package versions or blindly install a historical lockfile on a different platform. Use an isolated environment; do not replace system Python or unrelated dependencies.

A development assistant may itself have subscription or usage costs. That is separate from the finished application's runtime: generating cards, selecting passages, previewing and exporting in the finished app must not secretly call a paid cloud AI API or consume that assistant's account allowance.

Open-source dependencies are allowed. “No required third-party subscription” does not mean “no third-party libraries.” Do not make a separate paid desktop editor, cloud service or coding-assistant plugin necessary for daily use.

### 2. Product workflow and scope

The workflow is:

1. Import a YouTube URL, a local recording, a transcript file or pasted transcript text.
2. Generate up to eight source-supported headline-and-description cards.
3. Make those cards editable as soon as text generation finishes.
4. Prepare suitable video passages in the background when source footage is available.
5. Edit each card's content, visual settings, portrait and music.
6. Optionally switch individual cards, or all ready cards, into video shorts.
7. Select one, several or all cards and export only those finished MP4s.

Do not require exactly eight cards. If the source supports seven good ideas, seven is valid. Never display “Add exactly eight headline cards before exporting.” Support one through eight nonempty cards, adding a card manually, removing a card and editing existing copy.

This is a private local creation tool. Manual uploading of finished files to Instagram, LinkedIn, X/Twitter, YouTube and TikTok is the expected sharing workflow. Do not implement account connection, automatic posting or a scheduler. Do not promise platform acceptance solely because a video is under 500 MB.

Do not expand the scope with a caption-correction editor, terminology glossary, transcript-based editing UI, automatic music ducking, speaker-following camera tracking, saved brand presets, a project version-history system or platform safe-area overlays. Those are not requirements of this replication. Ordinary text-field undo supplied by the OS is fine.

### 3. Launching, installation and everyday use

Provide a double-clickable local application or equivalent launcher appropriate to this OS. The user should not need to run Terminal commands every time they open the app.

On macOS:

- Produce an app bundle with an Eightfold V2 title, a suitable icon, standard editing shortcuts and a proper Quit action.
- Start the backend on an available loopback port rather than assuming a fixed port is free.
- Wait for the server's actual address before loading the interface.
- Show useful startup progress and an actionable error if a dependency or data folder is missing.
- Terminate owned workers when the app quits. Do not leave duplicate background servers running.
- Make the file upload and directory chooser work inside WKWebView.

Keep the installation layout understandable. A self-contained app plus supporting folder is acceptable; do not claim an app bundle is independently portable if it depends on neighbouring files or an environment built for another machine. Supply setup, repair, launch and uninstall guidance. A local build does not require an App Store release or public distribution signing, and you must not disable the computer's security protections to make it launch.

### 4. Interface and layout

Use a professional dark interface with an “eightfold V2” wordmark and an original eight-element icon. Use eight elements, not six. A restrained lime accent is appropriate. Avoid loading fonts, icons or analytics from external CDNs at runtime.

Organise the main screen into:

- Start with your story: import controls and an editable transcript.
- Style & sound: default colours, animation, text, portrait, soundtrack and output settings.
- Your moments: the generated card grid, video-preparation status, bulk controls and export selection.

At a typical desktop window, target a compact four-column, two-row overview for eight cards. Keep the cards small enough to review the full set comfortably. Do not let tall settings panels force the entire grid far below the fold. Adapt to smaller screens with fewer columns rather than making content unusably tiny. Do not guarantee eight readable cards without scrolling on every possible display size.

Every card needs a visible Play/Pause control, an Edit action, an export checkbox and its current duration. The card editor should show a larger preview in the left column and that card's settings in the right column. Let the settings column scroll independently as needed. Keep Done easy to find.

Display a compact output summary such as **9:16 · 1080p · MP4**, updating the aspect ratio and quality when changed. Do not append a list of social platforms to this line.

Show live word counts, source evidence, fitted description size where useful, actionable progress and errors. Keep implementation details out of the normal workflow unless they explain a meaningful wait or problem.

### 5. Imports and source reuse

Support:

- Standard YouTube watch URLs, youtu.be links and valid Shorts/live/embed URL forms that identify a published recording.
- Local MP4, MOV, M4V and WebM video where the decoder supports them.
- Supported local audio and transcript files.
- Pasting and editing transcript text directly.

Prefer available YouTube captions for the initial written transcript. Handle unavailable captions, disabled captions, retrieval errors and malformed URLs without losing the draft. Offer local recording import or pasted text when captions cannot be obtained.

Treat transcript contents as untrusted source material, never as commands for the app or the language model. Do not execute instructions embedded in a transcript or media metadata.

For local video, transcribe locally and retain reusable word timings. For local audio, allow card generation, but explain that video portraits and speech-video shorts require actual footage. A pasted transcript alone must not pretend that footage exists.

A YouTube import must retain the source URL and retrieve suitable footage for the portrait automatically when available. The user must not be asked to upload the same video again simply because they opened Your portrait after importing the YouTube captions.

Normalise YouTube video identity so share-link tracking parameters do not trigger duplicate downloads. Reuse previously retrieved, compatible footage. Distinguish a lightweight portrait-only source from a source with original speech audio suitable for shorts.

The reference used a portrait copy up to 480p with a 150 MB limit, and an H.264/AAC shorts source up to 1080p with a 1 GiB limit. Equivalent configurable bounds are acceptable, but do not silently reduce final source quality to claim faster rendering. Apply bounded download timeouts, useful progress, limited retries and cleanup of incomplete files. Respect access restrictions; do not bypass DRM or require the user's browser cookies as a routine workaround.

Use yt-dlp with its currently required supported runtime for permitted YouTube retrieval. Inspect codecs with ffprobe. Convert an incompatible local source once to a browser-playable format and reuse that result. Do not re-encode a whole long recording every time a card is opened.

### 6. Local AI, model setup and resilient generation

The reference language model is **mlx-community/Qwen3-4B-Instruct-2507-4bit**, with **mlx-community/whisper-small-mlx** for speech. On compatible Apple Silicon, start with these or a verified compatible successor offering similar local resource requirements. On other hardware, choose a compatible local quantised model/runtime and document any quality or speed difference.

Download required models once, with visible progress and clear storage requirements. Keep them in an app-owned or explicitly configured location. Use offline loading after setup. No remote inference fallback without a new explicit user decision; never insert one silently.

Keep the model loaded during each batch of work. Do not reload it for every card or every editorial review. Do not assume keeping it resident forever is the largest optimisation; measure model loading separately and avoid unnecessary memory pressure on a 16 GB machine.

Handle long recordings of approximately 45–90 minutes and transcripts of 9,000–12,000 words or more. Bound each model request and its response size. Do not send an entire large transcript to a small local model and hope that one enormous JSON response works.

The reference card-generation approach:

- Divide normalised source text into numbered excerpts of roughly 75 words.
- Process bounded sections of around 16 excerpts, approximately 1,200 source words.
- Generate source-linked candidate cards and review them against that section.
- Select up to eight distinct useful cards through bounded shortlist operations.
- Avoid repeatedly embedding full source quotations in shortlisting prompts.

You may improve the internal efficiency if you can demonstrate preserved source fidelity. Do not substitute an unreviewed summary simply to achieve a shorter runtime.

Use strict structured response validation. Each candidate should include headline, paragraph, closing advice and supporting excerpt IDs. Use constrained JSON generation where the chosen runtime genuinely supports it, or bounded parsing/repair retries otherwise. Validate types, limits and evidence references before saving results.

If a section fails formatting, retry only within a bounded policy and split the section when appropriate. Retain complete validated work. If some sections cannot be processed, report incomplete coverage. Do not present a raw JSON exception such as “Expecting ',' delimiter” as the normal user experience. Do not loop forever or regenerate the whole project because one response failed.

Keep the transcript safe on every failure. Existing cards must not disappear because an AI request, download or renderer fails.

### 7. Headlines, descriptions and editorial rules

Every generated card contains:

- An editable headline of **at most 20 words**.
- An editable description of **at most 70 words**.
- Source evidence available in a collapsible context area.

The copy must stand alone for somebody who has never seen the original recording. It should explain the specific situation or pain, the useful advice, and why it matters. If it describes a problem, mistake, risk or issue, its final sentence must give practical advice or a solution actually supported by the source. If the source offers no remedy, choose another point rather than inventing one.

Do not refer to “the speaker,” “the presenter,” “the video,” “this clip” or “the transcript” in published headline/description text. Do not merely describe what someone demonstrates. Explain the useful takeaway directly.

Do not exaggerate certainty, turn an anecdote into a universal claim, invent numbers or guarantees, or add advice that sounds plausible but was not given. An evidence ID is not proof by itself: the review must compare the actual claim with the quoted source. Keep qualifications and conditions.

Never use hyphens, en dashes, em dashes or other dash characters in generated headline or description text. Rephrase compound words with spaces and punctuation dashes with suitable punctuation. Normalise and validate on generation, editing and export. Preserve the original quotation and verbatim speech captions; do not rewrite source speech just to apply the marketing-copy punctuation rule.

Descriptions must elaborate, not simply repeat the headline. Avoid repetitive closing advice and filler. Distinct cards should offer genuinely different points when the source permits them.

Provide Copy post text for the card. Do not automatically publish it anywhere.

### 8. Text-and-portrait card presentation

This is the default card format.

The **entire headline must be visible at 00:00**, because the first frame may be used as a social cover. Keep it visible throughout. Do not reveal the headline word by word, fade it in after an empty first frame, or crop its last line.

The complete description fades in beneath the headline and remains visible through the final frame. Provide:

- Fade in full description.
- Show all text together from the beginning.
- Reveal delay and fade duration controls, with sensible validation; the reference uses 0.25–2 seconds for each.

Do not split the description into disconnected stages that leave the full point absent at the end. Do not add the old green decorative dash above the headline.

Use large, readable typography, generous safe padding and line wrapping based on actual font metrics. Provide description size choices corresponding to 56, 64 and 72 pixels on the reference layout. Fit text separately for each aspect ratio and scale correctly for higher resolution. Reduce size only when necessary. Avoid clipping, collisions with a portrait and very small unreadable descriptions. Show the effective fitted size when it differs from the chosen size.

Use licensed fonts available on this machine or bundled with suitable redistribution rights. Do not assume a macOS system-font path exists on Windows or Linux. Ensure preview and export use matching fonts and layout calculations.

### 9. Automatic text-card duration

Remove the manual Clip length selector. Text-and-portrait cards automatically last **10–20 seconds** according to the amount of text and the reveal timing.

Use this reference calculation consistently in preview, portrait playback, music and export:

```text
headline_reading = headline_word_count / 3.3
description_reading = description_word_count / 3.3
reveal_time = reveal_delay + fade_duration when fading, otherwise 0
required = ceil(max(headline_reading, reveal_time) + description_reading + 1)
duration = clamp(required, 10, 20)
```

Editing content or reveal timing updates duration immediately. Ignore obsolete saved manual durations when migrating an older draft. Do not pretend 70 description words plus a headline are always comfortable to read within 20 seconds: the cap is intentional, and dense cards may require pausing or editing shorter.

Video shorts use their selected spoken duration instead of this reading-time formula.

### 10. Backgrounds, colour and animation

Provide a colour picker and editable **#RRGGBB** field globally and per card. Keep them synchronised and validate input. Derive supporting darker/lighter tones while preserving readable text contrast. Do not use a fixed palette selector as the primary colour control.

Provide background-detail opacity from 0–100%, globally and per card.

The background must contain independently animated elements with different depths, positions, phases, rotations and velocities. Scaling or sliding a single gradient image is insufficient. The movements should feel distinct and visibly respond to the selected motion and speed.

Include these six primary scene types:

- Floating layers.
- Flowing currents.
- Swirling layers.
- Expanding ripples.
- Flight through depth.
- Cascading layers.

Also provide Still, Slow drift, Push in, Side glide, Soft light pulse, Surging zoom, Wide orbit, Diagonal rush, Pendulum swing, Rhythmic bounce, Spinning zoom, Camera roll, Colour flow, Vertical sweep, Dramatic pull back, and Swoop and zoom, or faithfully equivalent named motions.

Include background details: Clean gradient, Fine rings, Soft grid, Starlight, Diagonal ribbons, Floating orbs, Wave lines, Confetti, Honeycomb, Sunburst rays, Contour lines, Nested diamonds and Scanlines.

Provide animation speed from **0.25× to 3×**. This changes the background motion only, not speech playback, portrait speed, soundtrack tempo or clip duration.

Use deterministic seeds and a shared animation clock so that a given card's preview and export match. Render animated backgrounds at an efficient working resolution if necessary, while preserving sharp full-resolution text and overlays in final exports. Do not render a fresh 4K effect merely to move a preview slider.

### 11. Portrait stills and moving portrait footage

Reuse the imported source footage. Do not require a separate photo upload and do not make users upload a video already available from their source import.

Provide a visual start-time slider with formatted source timestamps, not just a numerical seconds field. Show the available range and current frame. Let the user adjust horizontal crop, vertical crop and zoom. Crop and zoom must update visibly while dragging, without requiring a separate Preview click. Debounce frame extraction when scrubbing and discard stale responses.

Offer a still portrait or a moving circular mini video. A moving portrait starting at 0:35 on a 16-second text card plays the next 16 seconds of the source, starting at 0:35. Its source audio is muted; the card's soundtrack supplies audio. If the source ends early, hold the final frame for the remaining time.

Provide these global portrait positions and per-card overrides:

- At the top.
- Beneath headline.
- At the bottom.
- Do not show.

Keep the portrait clear of the headline, description and playback button. Store the start, crop, zoom, still/moving choice and position. Per-card overrides must not unintentionally alter other cards. Resetting a card's portrait override should restore inherited settings.

Provide **Choose portraits for all cards automatically**. It should scan the source once, detect clear faces locally, favour steady usable segments and assign a different suitable start/crop to each card in one operation. Prefer non-overlapping segments. If there are not enough suitable segments, leave remaining cards unchanged and report the count; do not silently pretend every card received a different segment.

Also provide per-card automatic selection and an option to select automatically after source import/card generation. Manual changes remain available. On macOS, use Vision face detection; elsewhere use a verified local detector. Detecting a face is not identifying the owner or understanding the spoken topic. Do not claim automatic identity recognition, and allow easy correction for interviews or multi-person footage.

### 12. Six progressive trance soundtracks

Provide **six instrumental progressive trance choices**, plus No music and an import-your-own-music utility. Do not add a soundtrack Mood selector or the previous multi-genre collection.

Use these musical directions and native BPM values:

| Name | BPM | Direction |
| --- | ---: | --- |
| Neon Ascent | 132 | Rolling sequencers, a clear rising lead melody, strong offbeat bass and energetic club percussion. |
| Glass Horizon | 128 | Airy plucked leads, sparkling arpeggios, a spacious major-key melodic lift and a clear answering phrase. |
| Midnight Vector | 126 | Dark resonant synth motifs, rolling bass, precise dry percussion and a tense late-night atmosphere. |
| Solar Bloom | 134 | A euphoric supersaw melody, bright independent counterlines and a full energetic groove. |
| Orbital Echo | 130 | A musical acid sequence, FM bell replies, evolving rhythmic layers and controlled hypnotic movement. |
| Aurora Tide | 136 | An expressive piano-led melody supported by trance drums, shimmering leads and string-synth harmonies. |

Each must have its own recognisable melody, instrumentation and arrangement. Six tempo changes of one chord loop are not acceptable. Avoid generic placeholder sine waves or calling a simple procedural chord bed a finished composition.

The reference app used locally generated ACE-Step 1.5 recordings, then retained the finished audio assets for playback. Assess whether local composition is feasible on this computer before starting large downloads. Use a separate temporary composition environment so it does not destabilise the app's inference runtime. Do not use a paid music API or copy a commercial song as a hidden substitute.

The exact original recordings are not included with this prompt. If I supply legitimately usable originals, retain them with their provenance. Otherwise compose six new originals following these directions, and clearly identify them as new recordings rather than identical copies of another installation's tracks. Do not hard-code a checksum belonging to an asset you do not possess.

Use original text briefs, distinct seeds and no copied melodies, samples, celebrity voices or encoded commercial reference recordings. If hardware or model availability blocks local composition, explain that specific limitation and continue the independently buildable app work. Do not claim the six-track requirement is complete with missing files or placeholder audio.

Generate and audition the recordings once. Card generation, preview and export must reuse saved music rather than composing again. A roughly 32-second source per track was sufficient in the reference because playback uses verified continuous musical sections.

There must be **no audible dips, quiet breakdowns, build-ups from silence or sudden drops during a clip**. Select energetic, steady, beat-aligned four-bar sections from the original recordings, loop them smoothly and exclude quiet sections. Use tiny click-removing edge fades/crossfades, not an audible fade-out in the middle. Maintain consistent perceived loudness across choices. Preview and export must use the same loop and tempo treatment.

Provide pitch-preserving tempo adjustment, approximately 70–160 BPM, and a music level control. Use the track's native BPM when choosing a different track unless an explicit intended override applies. Support soundtrack preview, switching before export and different choices per card.

Store a manifest containing track name, native BPM, description, file path, source/licence provenance, generation model/revision, prompt, seed, duration, checksum and loop information. Verify that recordings are playable, distinct and non-silent. Audition them; waveform statistics cannot establish musical quality.

Allow licensed audio import with a source/licence note. Do not call all imported or generated music “guaranteed copyright free.” Verify the actual model and asset licences, retain notices and explain that a permissive model licence does not guarantee exclusive rights or immunity from platform copyright claims.

Once assets are verified and the user approves removal, remove only this project's no-longer-needed composition models, temporary environment and duplicate generation files. Keep the finished recordings, loop assets, manifest and reproducible generation instructions. Never delete models used by unrelated apps.

### 13. Video-short preparation and format switching

Each card has **Text + portrait** and **Video short** formats. Default to Text + portrait. A video short uses the original recording's speech and imagery, not newly narrated card text and not a random moving portrait stretched to fill the frame.

After text cards are ready, prepare speech timings and suitable passages in the background. Show separate statuses:

- Cards ready: N editable now.
- Video passages: N of M ready.

Keep text editing available while footage or passages are being prepared. Track each card independently. Do not put downloading, full transcription or AI selection directly inside the format-toggle event handler.

Once a card is ready, format switching should be almost immediate and comfortably below ten seconds on suitable hardware. Returning to text should also be immediate. Preview the original cached source directly with timestamp seeks. Final MP4 rendering happens on export, not on every format change.

Do not promise that first-time import, a whole 75-minute transcription, preparation of all eight passages or 4K export finishes in ten seconds. Distinguish cold preparation from switching a ready card.

Preserve the card's written copy, portrait, visual choices and music settings when switching formats. Preserve its selected video passage and manual trims when switching back to text.

Use word timestamps for aligned speech captions and sentence boundaries for editorial selection. Cache these independently from card styling. Validate that video-short sources contain playable video and original audio.

### 14. The current, faster passage-selection design

Implement the optimised V2 approach. Do not recreate the slow pipeline that repeatedly ranks, edits and rejects continuous passages for each card before starting a second stitched-selection pipeline.

The intended process is:

1. Build a sentence index from the timed transcript, preserving actual spoken words, punctuation and gaps.
2. Use the headline, description and source quotation to retrieve relevant sentences with neighbouring context. Use frequency-weighted relevance rather than generic keyword counts alone.
3. Generate candidate excerpts from whole sentences. Include clear beginnings and completed endings; filter obvious interruptions and dangling references where possible.
4. Calculate valid continuous and joined edit plans in ordinary code before asking the AI. Plans should already satisfy chronology, non-overlap, padding and total duration.
5. Present continuous and stitched possibilities in the **same selection step**. Store each source sentence once in the prompt and refer to its IDs from the plans. Do not repeat the same long paragraph inside dozens of overlapping alternatives.
6. Give specific headline evidence more weight than incidental words from a surrounding quotation. Where a distinctive headline term occurs in its quoted evidence and the source, a generic passage omitting that evidence should not displace the specific point.
7. Ask the local model to choose one available plan ID, or indicate no suitable plan. Resolve only actual available IDs; never trust invented timestamps.
8. Run a separate final editorial review of the selected speech, adjoining context and omitted speech between cuts. Require all checks to pass: support for the headline, understandable opening/joins, preserved meaning/qualifications, and a completed useful takeaway. A problem clip must include the spoken solution/advice.
9. If a plan fails, remove it from further attempts. Do not review the same rejected plan repeatedly. Bound attempts, for example to three selection/review attempts per card.
10. Return a ready passage only after validation. Cache the result and captions. If nothing qualifies, keep the text card available and explain the limitation.

A practical implementation can build about 24 continuous candidates and 12 diverse joined alternatives from a bounded relevant sentence pool. Calculate lengths and merge overlaps locally. These are implementation starting points, not a reason to sacrifice a clear opening or exceed the model's context window.

Prefer concise, complete speech over loosely related material. Automatic excerpts may be as short as about three seconds when meaningful; the total must stay **below 60 seconds**, with a 59.9-second upper bound. The reference automatic planner combines up to three excerpts. Support editing/rendering existing selections with up to four chronological source segments. Manually trimmed selections may be shorter, subject to a valid minimum such as one second total and usable individual segments.

Preserve the original speech order. Do not fabricate transitions, rewrite spoken words, splice away a negation or necessary condition, change speaker meaning, or turn a complaint into an apparent endorsement. The headline overlay cannot rescue irrelevant speech. Similar cards may reuse a relevant passage if necessary, but do not assume eight distinct headlines guarantee eight unique source passages.

The format change must use the prepared result. Styling changes must not restart editorial selection. Text/source changes should invalidate the relevant match and prepare a replacement without destroying usable manual edits. Identify stale work by source and card-content identity so late results cannot attach to a different recording or modified card.

### 15. Video-short layout, captions and trimming

With captions enabled, use the upper two thirds of the card for source video and the lower third for synchronised speech captions. Put the full headline over an appropriately backed area near the bottom of the video region. It must be visible from the very first exported frame and stay visible throughout.

Provide **Fit whole video** and **Crop to fill** per card. Default new shorts to Fit whole video to preserve screen demonstrations and source content. Turning captions off lets the video fill the available card; the headline remains visible.

Use a matching opaque background for the title backing and caption panel, such as the reference colour **#111716**. Avoid the faint horizontal seam caused by a translucent title backing meeting a different solid caption colour. Account for fractional browser pixels at the two-thirds boundary. Preview and export should match visually.

Speech captions must follow the original timed words, not the card description. Group them into readable short phrases and render them sharply. For stitched clips, recompute caption times on the cumulative output timeline so omitted gaps do not create blank waits or incorrect captions.

Show the selected speech and each part's source start/end times in the editor. Provide start/end sliders for each segment. Keep starts/ends valid, preserve source order, prevent overlaps and enforce the total-duration limit. Refresh captions after trimming. Do not silently overwrite a manual trim when background preparation finishes.

Source preview must seek across omitted ranges, stop at the selected final end, pause/resume properly and replay from the first selected segment. Do not play through the source gaps, restart unexpectedly when reopening the editor, or leave audio playing after a preview is closed or cancelled.

### 16. Music on video shorts

Video shorts always retain their original speech. Background music is optional and initially off. Give shorts a **separate default music level of 15%**, so they do not inherit a text card's much louder soundtrack level.

Provide per-card music enabled/disabled, soundtrack, BPM and volume controls. A card can inherit the global track or select its own. No music or 0% music volume must leave the original speech audible.

Mix source speech with music in preview and export. Preserve source speech level at ordinary volumes and include a peak limiter to avoid clipping in the exported mix. Do not accidentally normalise the mix in a way that halves the speech level.

Use one continuous music clock across a stitched short. Do not restart the track at each source cut. Music must follow cumulative output time, pause during source buffering or pause, seek correctly, reset for replay and stop when preview is cancelled or closed. Let the volume slider change music volume during playback.

Do not add automatic speech-based music ducking; the current requirement is a user-set background music level plus clipping protection.

### 17. Bulk controls and per-card overrides

Above the card grid provide **Apply to all current cards** controls:

- Convert to video shorts.
- Show captions.
- Crop to fill.
- Add background music.
- Video music level.

These are immediate actions on the current cards, not a hidden rule that silently changes cards later. If only some cards have a setting enabled, display a mixed/indeterminate checkbox. Show a mixed indication when music levels differ.

Applying a control changes that specific setting across current cards. Editing a card afterwards overrides it again. Applying the bulk setting later replaces those corresponding overrides deliberately. Keep unrelated settings untouched.

Convert only cards with a prepared or retained usable passage. Report how many were converted and how many still need preparation. Do not secretly convert the skipped cards later when they finish; the user can apply the action again. Turning conversion off returns cards to text while retaining passages and trims.

Caption/crop/music settings may be stored while a card is still in text mode and take effect when it becomes a video short. Do not treat export-selection checkboxes as the scope of “all current cards”; export selection and bulk styling are separate concepts.

### 18. Export selection, formats and output files

Every card has an Export card checkbox. Provide Select all and Clear selection. The main action states how many clips will export. Support one selected card, any subset and mixed text/video-short exports.

Keep filenames associated with original card positions: choosing cards 2, 5 and 7 produces **02.mp4, 05.mp4 and 07.mp4**, not a silently renumbered 01/02/03 sequence.

Support these exact output sizes, rounding to even pixel dimensions where necessary:

| Aspect ratio | 1080p setting | 4K setting |
| --- | --- | --- |
| 9:16 | 1080 × 1920 | 2160 × 3840 |
| 1:1 | 1080 × 1080 | 3840 × 3840 |
| 16:9 | 1920 × 1080 | 3840 × 2160 |
| 4:3 | 1440 × 1080 | 3840 × 2880 |

Use H.264 MP4, 30 fps, yuv420p, fast-start metadata and AAC where audio exists. Preview can use a longest edge around 960 pixels. Final typography must be rendered at the requested output resolution, not upscaled from a small preview.

Probe the actual hardware encoder. On Apple Silicon, use VideoToolbox where it works and fall back to software H.264 if unavailable or unsuccessful. On other platforms use a verified suitable encoder, with a software fallback. Do not rely only on an encoder appearing in a list.

The reference uses target video bitrates around 2.5 Mbps for 1080p and 4 Mbps for 4K, with bounded peaks around 4 and 6 Mbps respectively. These are starting points: check real moving footage, readable text and file sizes. Use efficient compositing and temporary files rather than rendering an unnecessary silent deliverable and then duplicating it.

Enforce a final size check of **less than 500,000,000 bytes per MP4**. If a file exceeds the limit, report it and offer an appropriate lower-quality export; do not silently publish an oversized or incomplete file. This is a size safeguard, not a claim that every social platform accepts every supported aspect ratio or resolution.

The chosen export folder must contain **only the selected finished MP4 clips**. No posters, duplicate silent MP4s, ZIP archive, captions.txt, MUSIC.txt, project.json or intermediate media in the delivery folder. Keep project/provenance records internally.

A text card with No music may be silent. A video short with No music still contains its original speech.

Render into a temporary working directory and publish completed outputs safely. Handle a failed render without labelling partial results complete. Preserve existing exports. Give accurate progress rather than freezing the interface during a long 4K batch.

### 19. Choosing an export destination

Provide a real OS directory chooser, a visible selected path, Use Downloads and Use default buttons. The user must be able to select the Downloads folder itself or a specific nested folder. Do not use a file-only chooser that makes directories impossible to select.

Create a new, uniquely named export batch folder beneath the chosen destination, for example `Eightfold-V2-<timestamp>-<id>`. Do not overwrite unrelated files or earlier exports. Check writability and handle cancellation without erasing the previous choice.

On macOS, call the directory panel from the owning application/window on the main UI thread. Configure it for directories, allow new folders and label the action Use this folder. Validate native bridge messages against the expected local origin. Support the relevant OS permissions or bookmarks if the chosen packaging requires them.

After success, let the user reveal the exported files in Finder or the platform's file manager.

### 20. Persistence, task management and caching

Autosave the editable transcript, source identity, cards, overrides, portrait choices, selected passages, manual trims, music choices, export selection and destination locally. Use atomic writes and a versioned schema. Restore the draft when the app reopens.

A card needs, at minimum: its identity, headline, description, evidence quotation, format, export flag, visual overrides, portrait overrides, soundtrack/tempo/level, short music enabled/level, captions flag, fit/crop choice, prepared passage metadata and selected short segments/captions. Separate saved defaults from actual per-card overrides; do not accidentally overwrite an override while redrawing the interface.

Keep distinct caches for downloaded sources, browser-compatible sources, timed transcripts, selected passages, portrait frames/segments, soundtrack previews and rendered previews. Key caches by source identity, relevant settings and algorithm versions. Styling changes must not invalidate speech timings or source downloads. Changed text must not reuse a passage as if it had been validated for unchanged copy.

Reuse successes on Retry preparation. Retry failed/completed jobs when explicitly requested, but deduplicate jobs already running. Invalidate stale rejection caches when the selector changes. Always create required cache directories before writing requests, including after storage cleanup. Prevent the historical missing `video-preparation/...-request.json` failure.

Use bounded background jobs, appropriate model/GPU serialisation and safe cancellation. Do not launch eight memory-heavy model instances simultaneously on a 16 GB computer. Keep model loads, source processing and final renders away from the UI thread.

Show actionable states for queued, downloading, transcribing, selecting, reviewing, ready, unavailable and failed. Retain useful partial results. Ignore stale responses from an older source/card generation. On restart, recover or clearly report interrupted work rather than showing a permanently active spinner.

### 21. Performance measurement

Instrument the actual stages separately:

- Time waiting in the queue.
- Source retrieval and compatibility preparation.
- Time waiting for the local AI worker.
- First speech transcription/timing versus a cached transcript.
- Language-model loading.
- Passage selection and review, including AI call count.
- Preview preparation.
- Export rendering and final file sizes.

Show a concise completion message such as “Speech timings reused; passage selection 1:32.” Store detailed local timing reports without sending telemetry elsewhere. Do not combine download time and AI time into a misleading percentage or claim a cached result represents fresh preparation.

Use one representative long source and the same cards for a before/after performance comparison. Give each selector an independent empty passage cache while sharing identical already-timed speech when measuring selection alone. Do not run competing GPU benchmarks simultaneously. Check the selected speech as well as the stopwatch.

The reference optimisation measured **225.081 seconds to 92.150 seconds**, with **43 to 18 AI calls**, on the same long source and eight cards. That is a historical 59.1% reduction in passage selection, not a guaranteed target for every computer or recording. It excludes downloading, initial transcription, generating the written cards and export. Model loading in the baseline was only 1.756 seconds, so keeping it resident was not the primary saving.

Do not promise a ten-minute whole workflow will become 92 seconds solely because of this benchmark. Measure this computer and report the actual scope and results.

### 22. Storage cleanup and local security

Provide a storage review that shows app-owned generated previews, drafts, exports and optional imported media, with estimated recoverable space. Allow the user to choose what to remove and make the consequences clear before deletion.

Track external export folders created by this installation. Cleanup may remove only those recorded app-owned batches, never an entire Downloads folder or exports belonging to an earlier Eightfold installation. Defend against path traversal and symlink escapes. Do not follow a forged project path into arbitrary files.

Keep model downloads and the transcript by default. Removing imported media must warn that portraits and shorts depend on it, clear invalid references and pause automatic preparation so deleted footage is not immediately downloaded again. Restart preparation only on an appropriate explicit user action or new import.

Keep the backend bound to loopback, not the LAN. Validate Host/Origin and protect mutating endpoints with an appropriate per-launch token or equivalent protection. Serve only approved app files and managed media IDs. Support byte-range media requests for efficient video seeking. Escape user/model text in HTML, validate numerical inputs, avoid unsafe shell interpolation and launch media tools with argument arrays.

No analytics, hidden telemetry, automatic uploads, stored social passwords or silent cloud inference. Internet use is for explicit source retrieval and dependency/model setup. Local imported-media work should function offline once setup is complete.

### 23. Implementation organisation

Use a maintainable structure rather than a single inseparable script. Separate modules or equivalents for:

- Launcher and native dialogs.
- Local server, project persistence and job management.
- Import and source retrieval.
- Model setup/inference and structured-response validation.
- Editorial card generation.
- Timed transcription and source metadata.
- Passage planning, final review and cache policy.
- Text layout and reading-time calculation.
- Animated backgrounds.
- Portrait detection, crop and segment preview.
- Soundtrack catalogue, loop processing and audio mixing.
- Text-card/video-short preview and export rendering.
- Destination handling and storage cleanup.
- Diagnostics and meaningful tests.

One shared set of layout/timing/configuration rules should drive previews and exports. Avoid maintaining two divergent copies of complex UI logic. If bundling requires a generated inline script, automate it and test source/bundle parity.

Provide a clean local API or equivalent internal interface for project save/load, imports, generation, preparation status/retry, portrait selection, soundtrack preview, card preview, export and cleanup. Long operations should return job IDs and progress rather than holding the UI request open indefinitely.

### 24. Verification and acceptance criteria

Run meaningful automated tests and real native/browser checks on this computer. Do not claim a test passed because code compiles, a button is visible or a mocked call returned success. Use synthetic media fixtures for precise audiovisual checks and a permitted real recording for an end-to-end test.

Verify at least:

1. Fresh installation, model setup, double-click launch, quit and relaunch with the draft restored.
2. A long transcript around 9,000–12,000 words, malformed model responses, bounded retries and transcript preservation after failure.
3. At most eight supported cards, fewer-card exports, word limits, no marketing-copy dashes and source-supported closing advice.
4. First and final frames of text cards: full headline at 00:00 and full description visible at the end.
5. Automatic 10–20 second timing, all aspect ratios, 1080p/4K typography and no clipped text/portrait overlap.
6. Independently moving background details, speed changes and detail opacity at both extremes.
7. Source reuse, visible live portrait crop/zoom, moving portraits, end-of-source holding, all four positions and per-card overrides.
8. Automatic portrait selection assigning different suitable segments and a clear result when insufficient faces/segments exist.
9. Ready-card format switching without a download, AI call or final render; switching back without losing edits.
10. Valid continuous and stitched plans, duration bounds, chronological cuts, preserved qualifications, final-review rejection and no repeated review of a rejected plan.
11. Specific source-evidence matching: a card about a wireframe must not receive unrelated generic design advice merely because it shares vocabulary.
12. Byte-range source preview, stitched seeking, pause/resume/replay, correct caption timing and cleanup of cancelled playback.
13. Headline present on the first and later frames of exported shorts, captions on/off, fit/crop and no faint title/caption boundary seam.
14. Bulk control mixed states, skipped unready cards, per-card overrides and safe return to text.
15. Six genuinely distinct playable soundtrack assets, steady loops without audible dips, tempo changes and matching preview/export playback.
16. Shorts with speech alone and speech plus music; zero music level preserves speech; music remains continuous across stitched cuts; volume changes affect the mix; exported audio does not clip.
17. Export one card and a nonconsecutive subset, including a mixed-format batch. The destination contains only those MP4s with correct numbering and each file is below the size limit.
18. Native folder selection for Downloads and a nested folder, cancellation, unwritable locations and paths containing spaces.
19. Retry, stale-result handling, successful cache reuse, interrupted jobs and recovery after cleanup removes working directories.
20. Cleanup scope, unrelated-file protection, separate-installation protection and no immediate re-download after media cleanup.
21. Hardware-encoder failure fallback, real output dimensions/codecs/durations and an actual performance report with clearly separated stages.

Inspect screenshots and rendered frames. Listen to exported audio and the music catalogue where the environment supports playback; if listening cannot be performed, say so instead of claiming an auditory judgement. Confirm original source audio is retained in shorts and muted in moving mini portraits.

### 25. Delivery and working instructions

Start by inspecting the machine and giving a brief implementation plan. Then carry out the work. Make reasonable implementation decisions within this specification. Ask only for information you cannot obtain locally or for permissions genuinely required by the environment, downloads, licences or destructive actions. Keep me informed during long model downloads and benchmarks.

Do not stop at “this is possible.” Build and verify the app. Do not silently omit a difficult requirement or replace it with a placeholder. If a specific dependency, platform or hardware limitation blocks a feature, state exactly what remains incomplete while finishing the independent work.

Deliver:

- The runnable local application and its complete source.
- Working dependency/setup scripts with pinned successful versions.
- Model identifiers/revisions and required licence notices.
- All finished permitted music/visual assets needed at runtime, with provenance.
- A concise START-HERE guide for launch, import, editing, shorts, export and storage cleanup.
- A troubleshooting guide covering model setup, blocked YouTube retrieval, folder access, unavailable footage, JSON errors and slow preparation.
- A validation report listing actual tests performed, measured timings, output sizes and any material limitations.
- Clear separation between temporary development/generation files and files required to run the app.

Finish by launching the app, exercising the main workflow, showing where it lives and explaining how to use it. Leave unrelated applications and files untouched. The result should be a usable personal Eightfold V2 implementation, not a proposal for one.

## END BUILD PROMPT

---

## Official implementation references

These are reference sources for the builder to verify when installing; they are not extra paid subscriptions:

- [MLX language-model runtime](https://github.com/ml-explore/mlx-lm)
- [Reference MLX Qwen model](https://huggingface.co/mlx-community/Qwen3-4B-Instruct-2507-4bit)
- [Reference MLX Whisper model](https://huggingface.co/mlx-community/whisper-small-mlx)
- [llama.cpp local inference and hardware backends](https://github.com/ggml-org/llama.cpp)
- [whisper.cpp local transcription](https://github.com/ggml-org/whisper.cpp)
- [FFmpeg documentation](https://ffmpeg.org/documentation.html)
- [yt-dlp source and installation documentation](https://github.com/yt-dlp/yt-dlp)
- [YouTube transcript API library](https://github.com/jdepoix/youtube-transcript-api)
- [ACE-Step 1.5 local music generation](https://github.com/ace-step/ACE-Step-1.5)

The quantitative performance comparison and existing-feature details in this specification come from the local Eightfold V2 implementation and its 27 September 2026 validation report. They are not vendor performance guarantees.