System Requirements Document for face-swap-footage

1. Introduction

face-swap-footage is a consumer creative-AI studio for producing a realistic face swap on a creator's own footage. The product's promise is stated plainly in the source: Realistic face swap on your footage. A creator brings footage and a face, sets up the swap, and receives a swapped take that is ready to review.

The product intent is a precise, serious instrument rather than a toy: the creator supplies real footage and a real face, the system performs the swap, and the resulting take is presented as a living artefact to be reviewed and kept. The audience is a maker audience — part performer, part sceptic — who needs both awe at the result and reassurance that the process is real, controlled, and theirs.

This document is the System Requirements Document for the product. It specifies the current delivery: anonymous entry, self-service enrollment, returning verification, face swap setup, durable swap records with processing status, and review of the completed swapped take.

2. System Overview

face-swap-footage is a web application with a custom first-party interface and an application-owned backend. A single active human actor — the Face swap creator — moves through a short, complete lifecycle:

1. An anonymous visitor arrives at Landing, which explains realistic face swap on their own footage and who it is for.
2. The creator establishes identity through Sign Up (self-service first use) or verifies a returning identity through Login.
3. The signed-in creator sets up a swap on New Face Swap by supplying footage and the face to swap in.
4. The submitted job is recorded durably and processed in the background; the creator can revisit My Swaps to see each job and its processing status.
5. When processing completes, the creator opens Swapped Take to review the resulting swapped take.

Delivery shape: custom UI, application-owned identity, durable state, and background automation. The face swap itself is an AI transformation performed by the backend; the human-facing interaction is owned by the first-party pages above.

Removed from scope

• None. No concept from the authoritative requirement thread has been removed.

2a. Product Interpretation and Delivery Boundary

The product is delivered as a first-party web application. All human-facing work — entry, enrollment, verification, setup, status review, and take review — is owned by the application's own pages. The face swap transformation runs as a background process owned by the application backend; the creator never operates that process directly, but always sees its observable state (queued/processing/ready/failed) and its result.

Identity is application-owned because the creator must privately own and resume durable, actor-specific state: their footage, their face image, their swap jobs, and their completed takes. Anonymous visitors can read Landing and reach Sign Up and Login; the swap setup, the swap list, and the take review are protected and require a verified identity. There is no differentiated permission model: every verified creator sees and acts only on their own swaps.

Current horizon: everything specified in this document. No future-horizon capabilities are declared in the source.

2c. Page Content and Component Coverage

Landing

• Information/state: anonymous public entry. States the product promise — realistic face swap on your own footage — and who it is for. Top rail of uppercase micro-labels reading FOOTAGE IN · FACE IN · TAKE OUT. Full-bleed generative face-field hero with the headline Realistic face swap on your footage set into the dark left third.
• Primary action: a single orange rectangular CTA, Set up your face swap, which begins the identity path (Sign Up for a new creator, Login for a returning one).
• Supporting actions: a quiet link to Login for returning creators.
• Domain entities: none persisted; the hero is a generative visual, not user data.
• Component responsibilities: hero canvas (generative face-field), headline block, top micro-label rail, primary CTA, secondary login link.
• States: loading — hero canvas initialises with a static first frame before motion begins; empty — not applicable; success — not applicable; error — if the hero canvas fails, the static frame and all text/controls remain fully readable and usable; recovery — reduced-motion preference renders a single static frame of the field.

Sign Up

• Information/state: anonymous identity-establishment surface for a new creator. Collects the minimum credentials needed to create an application-owned identity (email address and password).
• Primary action: Create account, which establishes the identity and continues into the signed-in product.
• Supporting actions: link to Login for a creator who already has an identity.
• Domain entities: creator identity (email, credential).
• Component responsibilities: credential form, inline validation, submit control, link to Login.
• States: loading — submit disabled with a progress indication while the account is created; empty — blank form with field labels; success — identity established, creator lands signed in on New Face Swap; error — invalid or already-registered email, weak password, or network failure shown inline with the form preserved; recovery — the creator corrects the field and resubmits, or follows the Login link.

Login

• Information/state: anonymous returning-verification surface. Collects the creator's existing credentials.
• Primary action: Log in, which verifies the identity and restores access to that creator's durable swaps and takes.
• Supporting actions: link to Sign Up for a creator without an identity.
• Domain entities: creator identity (email, credential).
• Component responsibilities: credential form, inline validation, submit control, link to Sign Up.
• States: loading — submit disabled with a progress indication during verification; empty — blank form; success — verified, creator lands on My Swaps; error — incorrect credentials or network failure shown inline without revealing which field was wrong beyond a generic message; recovery — retry, or follow the Sign Up link.

New Face Swap

• Information/state: signed-in setup surface. A two-slot instrument panel — Footage and Face — above a persistent bottom action bar. The instrument rail marks the current step with a solid orange block.
• Primary action: Start face swap, enabled only when both slots hold a valid file.
• Supporting actions: drop or choose a footage file in the Footage slot; drop or choose a face image in the Face slot; remove or replace either file before submitting.
• Domain entities: face swap job (footage file, face file, status, created timestamp), owned by the signed-in creator.
• Component responsibilities: Footage drop-slot (sharp 2px-cornered rectangle, hairline crosshair, mint caption; on drop, desaturated thumbnail overlaid with a frame-strip schematic), Face drop-slot (same treatment), validation messaging, persistent bottom action bar with the submit control.
• States: loading — submit disabled and a progress indication while the job is created; empty — both slots show their crosshair and caption; success — job created, creator is taken to My Swaps with the new job visible in processing; error — unsupported file type, oversized file, or upload failure shown against the offending slot with the other slot preserved; recovery — replace the offending file and resubmit.

My Swaps

• Information/state: signed-in, revisitable overview of the creator's face swap jobs. A ruled table-like list, not a card grid. Each row shows the job's footage reference, its status, and its timestamps in mint tabular numerals.
• Primary action: open a job — a completed job opens Swapped Take; a job still processing shows its live status and cannot be opened for review yet.
• Supporting actions: start another swap via New Face Swap; refresh the list to pick up status changes.
• Domain entities: face swap job (footage reference, face reference, status, created timestamp, completed timestamp), owned by the signed-in creator.
• Component responsibilities: ruled job list, per-row status glyph and mint tabular numerals, processing readout (mint frame counter and thin orange progress rule for the active job), empty-state message, link to New Face Swap.
• States: loading — ruled skeleton rows while the list is fetched; empty — a message that no swaps exist yet with a direct route to New Face Swap; success — rows listed with current status; error — fetch failure shown with a retry control; recovery — retry, or navigate away and return.

Swapped Take

• Information/state: signed-in review surface for one completed job. A full-bleed player with a right-hand metadata column of ruled label/value rows (frame count, timecodes, completion timestamp) in mint tabular numerals.
• Primary action: play and scrub the swapped take for review.
• Supporting actions: Download take — a single orange bar pinned to the base of the metadata column.
• Domain entities: swapped take (result media, frame count, duration, completion timestamp) belonging to one face swap job owned by the signed-in creator.
• Component responsibilities: full-bleed player, transport controls, metadata column, download bar, back link to My Swaps.
• States: loading — player area shows a progress indication while the take is fetched; empty — not reachable for a job that has not completed; success — take plays and metadata is populated; error — take unavailable or failed processing shown with a clear message and a route back to My Swaps; recovery — return to My Swaps and retry the job.

3. Functional Requirements

FR-1 — Set up a realistic face swap on own footage (explicit) As a Face swap creator, I should set up a realistic face swap on my own footage, so that my footage is transformed with the face I supply.

• Trigger/input: the signed-in creator opens New Face Swap and supplies a footage file in the Footage slot and a face image in the Face slot.
• Observable result: a durable face swap job is created, owned by that creator, and appears in My Swaps with a processing status.
• Access state: requires a verified creator identity.
• Failure/recovery: an unsupported, oversized, or failed upload is reported against the offending slot; the other slot is preserved and the creator can replace the file and resubmit.
• Continuation: the creator is taken to My Swaps to follow the job's status.

FR-2 — Review the swapped take once it is ready (explicit) As a Face swap creator, I should review my swapped take once it is ready, so that I can judge the result of the face swap.

• Trigger/input: the creator opens a completed job from My Swaps.
• Observable result: Swapped Take presents the full-bleed player with the take and its metadata (frame count, timecodes, completion timestamp); the creator can play, scrub, and download the take.
• Access state: requires a verified creator identity and ownership of the job.
• Failure/recovery: if the take is unavailable or the job failed, a clear message is shown with a route back to My Swaps.
• Continuation: the creator returns to My Swaps to review other jobs or start another swap.

FR-3 — Self-service enrollment for a new face swap creator (required_inference) As a Face swap creator, I should be able to create my own identity on first use, so that my swaps and takes are privately mine and I can return to them.

• Trigger/input: an anonymous visitor selects Set up your face swap on Landing and completes the Sign Up form.
• Observable result: an application-owned identity is established and the creator is signed in.
• Access state: anonymous entry; the resulting identity unlocks the protected pages.
• Failure/recovery: invalid or already-registered email, weak password, or network failure is shown inline with the form preserved; the creator corrects and resubmits or follows the Login link.
• Continuation: the creator lands on New Face Swap.

FR-4 — Returning verification before accessing protected face swap records (required_inference) As a Face swap creator, I should verify my identity when I return, so that I can reach my durable swaps and completed takes.

• Trigger/input: a returning creator opens Login and submits their credentials.
• Observable result: the identity is verified and the creator's own swaps and takes become accessible.
• Access state: anonymous entry to Login; verified session required for New Face Swap, My Swaps, and Swapped Take.
• Failure/recovery: incorrect credentials or network failure is shown inline without disclosing which field was wrong; the creator retries or follows the Sign Up link.
• Continuation: the creator lands on My Swaps.

FR-5 — Supply footage and face image to set up a swap (required_inference) As a Face swap creator, I should supply both my footage and the face to swap in, so that the system has everything it needs to perform the swap.

• Trigger/input: the creator drops or chooses a file in each of the Footage and Face slots on New Face Swap.
• Observable result: each slot shows a desaturated thumbnail overlaid with a frame-strip schematic and a mint caption; the submit control becomes enabled only when both slots hold a valid file.
• Access state: requires a verified creator identity.
• Failure/recovery: an invalid file is reported against its slot; the creator replaces it.
• Continuation: the creator submits with Start face swap.

FR-6 — Background processing completes before the swapped take can be reviewed (required_inference) As a Face swap creator, I should see my job's processing status until it completes, so that I know when the swapped take is ready to review.

• Trigger/input: a submitted face swap job enters background processing.
• Observable result: My Swaps shows the job's live status with mint tabular frame numerals and a thin orange progress rule; the job becomes openable for review only once processing completes.
• Access state: requires a verified creator identity and ownership of the job.
• Failure/recovery: a failed job is shown with a clear failed status; the creator can return to New Face Swap to try again.
• Continuation: on completion, the creator opens Swapped Take.

4. User Personas

Face swap creator

• Product context: a maker — part performer, part sceptic — who has their own footage and a face they want swapped into it, and who wants a convincing, realistic result they can review and keep. They arrive either as a first-time visitor or as a returning creator with existing swaps.
• Primary goal: produce a realistic face swap on their own footage and review the resulting swapped take.
• Distinct accepted responsibilities:
  • Establish their own identity on first use (Sign Up) or verify it on return (Login).
  • Set up a swap on New Face Swap by supplying both the footage and the face image.
  • Follow the job's processing status on My Swaps.
  • Review the completed take on Swapped Take, playing, scrubbing, and downloading it.
• Relevant inputs and decisions: which footage file to use; which face image to swap in; whether to submit, replace a file, or abandon a setup; when to open a completed job for review.
• Interactions with other accepted participants: none beyond the creator themselves; the background processing is a system actor, not a human participant.
• Observable success: a durable job appears in My Swaps, reaches a completed status, and its swapped take plays and downloads from Swapped Take.

5. Core User Flows

Flow A — First-time creator sets up and reviews a face swap

1. The visitor opens Landing anonymously and reads the promise: realistic face swap on their own footage.
2. The visitor selects Set up your face swap and arrives at Sign Up.
3. The visitor enters an email address and password and selects Create account. The identity is established and the creator is signed in.
4. The creator lands on New Face Swap. Both slots show their crosshair and caption.
5. The creator drops their footage into the Footage slot; the slot shows a desaturated thumbnail with a frame-strip schematic and a mint caption.
6. The creator drops the face image into the Face slot; the slot shows the same treatment. The Start face swap control becomes enabled.
7. The creator selects Start face swap. A durable job is created and the creator is taken to My Swaps, where the new job appears in processing with mint frame numerals and a thin orange progress rule.
8. The creator waits or leaves and returns later via Login. On return, My Swaps shows the job's current status.
9. When the job completes, the creator opens it and arrives at Swapped Take. The full-bleed player loads the take and the metadata column shows frame count, timecodes, and completion timestamp.
10. The creator plays and scrubs the take, then selects Download take to keep it.
11. The creator returns to My Swaps to review other jobs or start another swap.

Failure/recovery: if a file is rejected at step 5 or 6, the error appears against that slot, the other slot is preserved, and the creator replaces the file and resubmits. If the job fails during processing, My Swaps shows a failed status and the creator can return to New Face Swap to try again.

Flow B — Returning creator verifies and reviews an existing take

1. The returning creator opens Login anonymously.
2. The creator submits their credentials and selects Log in. The identity is verified.
3. The creator lands on My Swaps, which lists their existing jobs with current statuses.
4. The creator opens a completed job and arrives at Swapped Take.
5. The creator plays, scrubs, and downloads the take, then returns to My Swaps.

Failure/recovery: if credentials are incorrect, a generic inline message is shown, the form is preserved, and the creator retries or follows the Sign Up link.

6. Visuals Colors and Theme

The creative direction is authoritative: Data made flesh — a generative face-field under a single hot signal, after Refik Anadol.

Mode: dark only.

Colour tokens (exact hex by role):

Never a second bright accent; the generative artwork supplies all other colour.

Typography:

• Headings: Instrument Serif, weight 400 only, tracking -0.02em, sentence case, set enormous and allowed to break across lines.
• Body: Space Grotesk.
• Micro-labels and data: Space Grotesk uppercase at 11–12px with 0.14em tracking.
• Tabular numerals in Space Grotesk for all counters and timecodes.
• Scale (1.5 modular): display clamp(44px, 7vw, 112px) / h2 clamp(28px, 3.4vw, 48px) / h3 22px / body 16px / label 12px / mono-data 13px.

Shape language: almost no radii — 2px on inputs and buttons, 0 elsewhere. Full-bleed rectangles, 1px hairline rules, and a single soft-edged luminous circle as the only curved form (the face-field aperture). Sharp corners everywhere else.

Layout: museum-hang layout — full-viewport generative hero with a thin top rail of micro-labels; sections separated by full-width 1px rules on a 12-column grid with content in columns 2–8 and metadata hanging in column 11 as a right-aligned stack of small-caps values. New Face Swap is a two-slot instrument panel above a persistent bottom action bar; My Swaps is a ruled table-like list, not a card grid; Swapped Take is a full-bleed player with a right-hand data column.

Spacing rhythm: generous vertical rhythm between ruled sections; tight internal spacing within metadata stacks; consistent 1px rules as the primary separator.

Imagery style: generative particle and fluid fields derived from the user's own frame data; supporting visuals are macro crops of the swapped face dissolving into data texture and schematic frame-strip diagrams. No stock people, no device mockups, no gradient blobs.

7. Signature Design Concept

The face-field aperture. The public entry is a full-bleed black canvas filling the viewport. A slow, luminous face-shaped particle field — orange core #E8552A bleeding into mint #7DE2C3 at the edges — sits off-centre to the right, cropped by the viewport edge. Over it, on the left in columns 1–7, the Instrument Serif headline Realistic face swap on your footage is set at clamp(44px, 7vw, 112px) in #F2F3F5, stacked in three lines, with a thin rule beneath and a single orange rectangular CTA Set up your face swap pinned at its baseline. A top rail of uppercase micro-labels — FOOTAGE IN · FACE IN · TAKE OUT — runs the full width.

The concept recomposes only accepted content: the product promise, the single setup CTA, and the login path. It introduces no new behaviour. The single soft-edged luminous circle is the only curved form on the page; every other corner is sharp so the generative glow is the only softness.

8. Interaction Model & Motion Direction

Interaction Model: Animated Motion Tempo: cinematic Hero Dimensionality: webgl

Landing Hero Motion Brief

• Focal subject: a slow, luminous face-shaped particle field, orange core bleeding into mint at the edges, off-centre right and cropped by the viewport edge.
• Input → transformation → outcome thesis: as the visitor scrolls, the face-field morphs and drifts, revealing the product's promise — footage in, face in, take out — while the headline stays set into the dark left third; the single orange CTA remains pinned at the headline's baseline.
• Motion vocabulary: continuous slow generative flow at ~24fps, scroll-linked morph, slow crossfades for reveals, 200ms functional transitions on controls. Never slides or bounces.
• Composed first frame: full-bleed black canvas; face-field settled off-centre right; three-line Instrument Serif headline left; thin rule beneath; orange CTA at the baseline; top micro-label rail across the full width.
• Reduced-motion state: the hero renders a single static frame of the field and all state changes become instant.

Landing Hero 3D Scene Brief — DIRECTION-DERIVED

A real-time WebGL/R3F scene renders one crafted subject: a face-shaped particle field whose density and colour gradient encode the product's defining state — a face becoming a flowing field of pixels. The scene is immersive, full-bleed, and scroll-linked; it never covers readable text or controls, which sit in the dark left third and top rail.

9. Non-Functional Requirements

• NFR-1 — Durable state (explicit via Planning Scope): face swap jobs and their resulting takes persist across sessions and are bound to the creator who created them.
• NFR-2 — Application-owned identity (required_inference): identity is established by the application; protected pages are inaccessible without a verified session.
• NFR-3 — Background automation (required_inference): face swap processing runs asynchronously; the creator is never blocked waiting on it and can leave and return.
• NFR-4 — Readable text and controls at every viewport (explicit design constraint): headlines, wordmarks, labels, numbers, and controls stay entirely inside the viewport and their container at 375px, 768px, and 1280px, wrapping or scaling to fit; no other element covers any part of them. Imagery and motion may be cropped or bled off an edge as the direction asks, provided they cover no readable text or control.
• NFR-5 — Reduced motion (explicit design constraint): with prefers-reduced-motion, the hero renders a single static frame and all state changes become instant; any scrollable content remains fully reachable.
• NFR-6 — Single bright accent (explicit design constraint): only #E8552A is a bright accent; #7DE2C3 is reserved for data. No blue/indigo accents, no white ground, no gradient blobs, no glassmorphism.

10. Tech Stack

• Frontend: React with a WebGL/R3F hero scene for the generative face-field.
• Backend: Python / FastAPI, extended with routes and modules for identity, face swap jobs, and take retrieval.
• Storage: durable storage for creator identities, face swap jobs, uploaded footage and face files, and resulting takes.
• Background processing: an asynchronous worker process that performs the face swap and updates job status.
• Deployment: Docker / docker-compose for the frontend, backend, worker, and storage services.

11. Assumptions and Constraints

• A-1 (required_inference): The creator supplies exactly one footage file and one face image per swap.
• A-2 (required_inference): A swap job has a status lifecycle of at least processing, completed, and failed; only completed jobs are openable for review.
• A-3 (required_inference): Every verified creator sees and acts only on their own swaps; there is no differentiated permission model.
• A-4 (explicit design constraint): The interface is dark-mode only, using the exact palette and fonts in Section 6.
• A-5 (explicit design constraint): The generic indigo/blue-on-white SaaS template is forbidden.
• A-6 (required_inference): The face swap transformation is performed by the application backend; no third-party provider surface is part of the accepted delivery.

12. Glossary

• Face swap creator — the single active human persona; the user who supplies footage and a face and reviews the resulting take.
• Footage — the creator's own video file into which a face is swapped.
• Face — the face image supplied to be swapped into the footage.
• Face swap job — a durable record of one setup: footage, face, status, and timestamps, owned by one creator.
• Swapped take — the resulting video produced by a completed face swap job, reviewed on Swapped Take.
• Face-field — the generative particle/fluid visual derived from frame data; the product's signature imagery.
• Instrument rail — the persistent top rail of uppercase micro-labels on signed-in pages, with the current step marked by a solid orange block.