Creators publishing a video, for example to YouTube, usually have to write a description, mark chapter timestamps, pick SEO keywords, choose a thumbnail, and write captions. VidPrep prepares drafts of these outputs from a video or audio file you upload, using Snowflake Cortex. It does not download videos from YouTube or other sites; process only media you own or have rights to use. Review the transcript and generated copy before publishing; transcription and model output can contain errors.

The core design principle behind VidPrep is that a large language model should never be trusted to emit a timestamp directly, because it can hallucinate one that doesn't correspond to anything said in the video. Instead, the model is only ever asked to point at a position in a real, transcribed word array, and the actual timestamp is looked up in code from that position. This guide walks through that architecture and how to build and deploy the whole app on Snowflake.

Read the solid arrows as processing order, not unconditional execution: cached results can skip work, and extras run only when requested. The warehouse provides the SQL query context; Cortex runs AI inference on its own compute. The diagram's warehouse arrows indicate SQL calls, not the location of model execution.

VidPrep, a Streamlit-in-Snowflake app, with:

Screenshots of each part appear in the sections that build it. They come from one live run on the synthetic sample video in the companion repository, so you can upload the same file and compare your results.

Use a dedicated tutorial environment, and record which resources you create. Do not reuse or replace another project's app. Cortex calls and container compute incur usage charges.

Run the following as a role with sufficient privileges. This creates a dedicated warehouse, database/schema, an internal stage (used to hand media files to AI_TRANSCRIBE), a compute pool for the Streamlit container runtime, and an External Access Integration so the container runtime can install the Python dependencies in pyproject.toml from PyPI (container runtime apps have no PyPI access by default).

The app's pyproject.toml is short. Besides Streamlit and the Snowflake connector, it only needs imageio-ffmpeg for a bundled ffmpeg binary, because the container runtime has no system ffmpeg:

The app never opens its own Snowflake connection. It uses st.connection("snowflake"), which reads local secrets during development and the app's embedded identity once deployed (the same code path either way):

For local development, use an existing named Snowflake connection without copying credentials into the project. Start the app with the intended profile explicitly selected:

Confirm that profile targets the intended account and has access to the configured stage. Hosted Streamlit uses its embedded identity. For isolated tests, set VIDPREP_STAGE_FQN to a test-only stage and VIDPREP_CACHE_DIR to a fresh local directory. Stage names must contain three unquoted identifiers. Never commit connection credentials.

acquire.py saves the uploaded file and wraps it in one AcquiredMedia object that the rest of the app consumes. Start with media you own or are authorized to process. Uploads use unique temporary filenames, so an uploaded filename cannot overwrite another file, and the cache key is a hash of the file's contents:

Uploaded video files double as the preview player's source and the input for thumbnail frame extraction. Audio-only uploads get an audio player instead, and the thumbnail tab reports that no video frames are available.

In the app, this is the Input section: a single file uploader and a Generate button. Here the sample video vidprep_demo.mp4 has been added and is ready to process:

transcribe.py builds a single transcript timeline for the media. Downstream timestamps are resolved against that timeline, so their accuracy depends on the transcription.

AI_TRANSCRIBE has a practical limit on media length when requesting word-level timestamps, so longer media is split into chunks with ffmpeg, transcribed independently, and re-based onto one continuous timeline using each chunk's measured duration (not the requested split point, which can drift):

Cleanup is attempted even if transcription or response parsing fails. A cleanup warning means you should inspect the stage and remove only the files from your own run. Transcripts are cached by a hash of the uploaded file's contents, so uploading the same file again reuses its transcript.

This is the section that enforces VidPrep's core correctness rule. generate.py never asks the model for a timestamp. It only asks for a word_index into the transcript array it was shown, tagged inline as [INDEX]word:

The AI_COMPLETE call requests structured JSON with this schema. A request can occasionally return NULL, so the helper retries a bounded number of times before reporting an error:

The generated result and each extra (titles, quotes, FAQ) are cached under a key that includes a hash of the model and the inputs the prompt uses, so a changed transcript or regenerated result never reuses stale suggestions.

This app uses claude-sonnet-5 as the AI_COMPLETE model, set by COMPLETE_MODEL in config.py. That model isn't hosted in every region. If your region doesn't offer it, either enable cross-region inference as ACCOUNTADMIN:

or change COMPLETE_MODEL to a model that is available in your region (see model availability) and redeploy. The cache key includes the model name, so switching models never reuses old results.

The transcript is scanned in overlapping word-count windows rather than one full-transcript call. Returned indices are converted to integers and clamped to the transcript's bounds. This keeps timestamps within the transcript; it does not establish that the selected chapter boundary is suitable:

A second AI_COMPLETE call, given the combined per-chunk summaries, writes the description and suggests SEO keywords in the same structured response:

The Overview tab shows the result. For the two-minute sample, the model proposed eight chapters, and each start time (0:00, 0:16, 0:30, and so on) was looked up from the transcript word it pointed at. Each timestamp is a button that seeks the preview player. Below them, the description block combines the generated description, the chapter list, and the keywords, ready to paste into a video platform:

enhance.py layers six more publishing-prep features on top of the core pipeline, following the same "never invent, always resolve" rule:

On the Titles & SEO tab, the sample produced eight title candidates. The checklist passed four checks and flagged one: none of the 15 keywords appear word for word in the description. That warning is the point of the checklist: it tells you what to fix by hand before publishing.

The Thumbnails & Clips tab shows both. Each thumbnail is a real frame taken two seconds after a chapter start (0:02, 0:18, 0:45, and so on), labelled with that chapter. Each pull quote is copied exactly from the transcript with its real time span, such as "A language model should never invent a timestamp." at 0:59 to 1:01:

The Captions & FAQ tab has the two caption downloads at the top. Below them, each FAQ entry ends with a "See" link to the chapter it came from, and the copy-paste Timestamps block lists every question at its chapter's start time:

Treat all of this generated copy as a first draft and review it before publishing.

app.py wraps the Input controls in a bordered container, then, once a result exists in st.session_state, renders the Output section as four tabs. The tab set has a key and on_change="rerun" (available in Streamlit 1.64 and later), so the selected tab survives the rerun that every button click triggers. Without it, clicking an extras button would send the user back to Overview:

The three "extras" tabs are lazy: each has its own Generate button, and results are kept in st.session_state["extras"] so switching tabs doesn't lose them or re-trigger a model call:

The app clears previous media, transcript, results, extras, and the selected tab when Generate is clicked, including when input is missing or the next request fails. A failed request therefore cannot leave another video's output displayed as its result, and each new result opens on Overview.

If a model call still returns no result after its retries, the tab shows a "Generation failed" message. Click that tab's Generate button again; earlier results stay in place.

VidPrep runs on the Streamlit-in-Snowflake container runtime, using Python dependencies and the ffmpeg executable bundled by imageio-ffmpeg. The only outbound access it needs is PyPI, for installing those dependencies when the container starts.

Define the deployment in snowflake.yml:

Check that snowflake.yml references the resources you created in Setup. If you chose different names, update the identifier, warehouse, compute pool, integrations, and config.py stage default together. Confirm each listed artifact exists and no credentials are included. Use a distinct app name for a test deployment; --replace must not overwrite an app you need to preserve.

The first deploy resolves and locks Python dependencies inside the container, which can take a few minutes. If you later change pyproject.toml, redeploy with --prune to clear the stale lockfile left on the stage. The keyed output tabs require Streamlit 1.64 or later; if the deployed app fails on st.tabs, confirm the container resolved a version that satisfies the pyproject.toml floor.

1. Upload a short original video and select Generate. If you don't have one, use sample/vidprep_demo.mp4 from the companion repository: a two-minute synthetic narrated demo with eight sections and no real people or data. The screenshots in this guide were produced from it. Confirm a description, ordered chapter timestamps, and a working local preview appear. Click a later chapter timestamp and confirm the preview player moves to that time.
2. Generate titles/SEO suggestions, thumbnails, pull quotes, and an FAQ from their respective tabs. Each tab should stay selected after its Generate button runs. Download both caption formats and inspect their text and timestamps.
3. For a fresh live check, use a new cache directory and test stage. A cached result or a mocked unit test is not proof of a new Snowflake call.
4. Review transcription accuracy, generated claims, and chapter suitability manually. Resolved timestamps refer to transcript entries; they do not guarantee correct transcription or ideal chapter boundaries.

Save any generated outputs you need, and stop the local app if you started one. Then run the following as the role you used in Setup. Stopping the compute pool's workloads first is required before it can be dropped. Dropping the database also removes the stage and any media left on it.

Finally, delete the local cache directory (.cache by default, or whatever you set VIDPREP_CACHE_DIR to) to remove cached transcripts, thumbnails and caption files.

VidPrep turns an uploaded video into draft publishing materials: chapters, a description, titles and keywords, thumbnail candidates, pull quotes, captions, and an FAQ. Chapter timestamps and quote spans are resolved from transcript data in code. Review those outputs before publishing.

Documentation:

Additional Reading: