Reveal

Inspiration

Imagine watching a mystery with friends. They see an unidentified visitor. The audio description gives you her name before the film does.

For someone relying on description, access to the action should also preserve the chance to experience suspense. We built Reveal around a focused question: can we help an editor spot premature identity disclosures before narration is recorded?

This fits an existing professional workflow. Audio-description teams watch the film, write and review timed scripts, record narration, and mix the final track. Reveal adds assistance during script review. Descriptive Video Works describes that process here.

Our desk research found a direct editorial basis: Netflix's audio-description guide generally recommends introducing character names when the story establishes them, with context-dependent exceptions. That is why Reveal presents findings for human review instead of automatically removing names. Netflix's guidance, section 1.2 / WHO.

What it does

An editor uploads a movie clip and a separate timed audio-description draft in SRT format, with optional filmmaker intent notes. Embedded captions are not required. Audio description conveys visual details for blind and low-vision audiences; ordinary captions convey speech and relevant sounds. Reveal focuses on the description script. W3C's explanation of visual description.

Gemini compares the video, timed cues and notes, then returns possible identity disclosures, explanations, evidence intervals and proposed wording. The editor inspects the scene, edits and accepts a suggestion, dismisses it, or marks the wording intentional. Accepted decisions determine the exported SRT.

In our synthetic demonstration, the draft names Mara at five seconds, while the film reveals her staff badge at 66 seconds. Filmmaker notes specify the intended reveal. The reviewer changes the description to “A hooded visitor waits in the theater lobby.” This is a controlled example with supplied intent, not an independent identity-recognition benchmark.

Judges can open a clearly labelled recorded Gemini example without using model quota. Each copy supports playback, editing and export. Fresh analysis is a separate action.

How we built it

Reveal is hosted on Replit and was set up there with Replit Agent. After importing the repository, Replit Agent configured the development workflow, Vite host and proxy settings, PostgreSQL compatibility and deployment configuration. That contribution is preserved in setup commit 9e29ce1. The published app serves the React editor and FastAPI API together, with credentials stored in Replit Secrets.

The backend executes a Google ADK LlmAgent through a Runner. It sends a private Cloud Storage video reference, timed cues and filmmaker notes to Gemini on Google Cloud Agent Platform. Structured findings pass through cue and timestamp validation before editorial review. ADK runs inside the Replit process; there is no managed Agent Runtime deployment. Temporary Cloud video objects are removed after requests on a best-effort basis.

The stack includes React, TypeScript, Vite, Python, FastAPI, SQLAlchemy, PostgreSQL/SQLite and FFmpeg/ffprobe. An optional Gemini Developer API path remains available through the Google Gen AI SDK and Files API.

Initial application development used Gemini in Antigravity. Replit Agent handled the setup described above. Codex also contributed planning, implementation fixes, review, tests, documentation and demo production. The narrated demo uses ElevenLabs, HyperFrames and FFmpeg.

Challenges we ran into

Preserving editorial intent. Multiple accepted findings can affect the same cue. We added cue-level resolution and regression tests to preserve custom wording without restoring concealed names. Reanalysis preserves human decisions and flags changed accepted proposals for re-review.

Keeping exports trustworthy. Reconstructing SRT files can alter line endings, padded cue IDs and spacing. Reveal replaces text within the original bytes, with tests covering BOM, CRLF, multiline revisions and unchanged content.

Handling provider and deployment failures. Gemini calls can fail because of quota or temporary demand. Those failures remain visible instead of silently producing heuristic results. Recorded examples provide a labelled path for exploring the editor. Bundled media uses a versioned reference so it survives deployment path changes; user-uploaded media still needs durable production storage.

Accomplishments that we're proud of

• A working video-and-script review loop using Gemini, with a fresh hosted Google ADK/Agent Platform analysis independently verified.
• A specific editorial problem grounded in published audio-description guidance.
• Human-controlled decisions, re-review context, accessible text review, video seeking and formatting-preserving export.
• A reproducible automated suite covering backend integrity and browser interactions. These engineering checks do not measure model accuracy or audience outcomes.
• A 2:41 narrated demo showing the problem, editorial workflow, recorded successful Gemini results, and Replit's contribution. It does not show a fresh inference completing during recording.

What we learned

A name may be a spoiler in one scene and essential for clarity in another. A useful review tool needs to provide context and leave the decision with the editor.

We also learned to separate a plausible benefit from a measured outcome. Research estimated 43.3 million blind people globally in 2020. That explains the scale of the accessibility context; it is not Reveal's market size or user count. We have not yet measured accuracy, time savings or audience impact. Population study.

What's next for Reveal

Evaluate with professional describers and blind and low-vision participants. Build an annotated collection of reveal and non-reveal scenes to measure false positives, missed issues, reviewer effort and comprehension.

Longer-term work includes full-film context, additional script formats, a formal accessibility audit, separate accounts, durable media storage and model-usage controls. The current hosted app is a shared public demo intended for non-confidential test material.

Built With

• fastapi
• ffmpeg
• gemini
• google-adk
• google-cloud-agent
• postgresql
• python
• react
• replit
• sqlalchemy
• sqlite
• typescript
• vite