> For the complete documentation index, see [llms.txt](https://staylime.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://staylime.com/docs/volume-themes/sections/media/video.md).
# Video
Give one video a section of its own — YouTube, Vimeo or a Shopify-hosted file, with your own cover image and a play button the visitor chooses to press.
Video sells what photography can't: how a fabric moves, how a product is actually used, who is behind the brand. The **Video** section gives a single video a full section to itself — your own cover image, your own framing, and a play button the visitor presses when they're ready. Nothing autoplays, nothing competes with it, and the page doesn't pay for the video until someone asks for it.
{% hint style="info" %}
**At a glance**
| Where to find it | **Add section → Media** |
| ---------------- | ----------------------------------------------------- |
| Sources | A Shopify-hosted video file, or a YouTube / Vimeo URL |
| Allowed on | Any template — not the header or footer groups |
| Typical use | Brand film, product demo, lookbook, founder story |
| {% endhint %} | |
***
### How to add
{% stepper %}
{% step %}
### Add the section
Click **Add section** and pick **Video** from the **Media** group.
{% endstep %}
{% step %}
### Choose one source — not two
Either upload a file into **Video** (hosted by Shopify) or paste a link into **Video URL** (YouTube or Vimeo). The field arrives pre-filled with a sample YouTube link, so replace it rather than leaving it next to an uploaded file.
{% endstep %}
{% step %}
### Upload a cover image
**Cover image** is what the visitor sees before pressing play — treat it as a still from the film, not a placeholder. It is also the only part of the section that loads with the page.
{% endstep %}
{% step %}
### Add a mobile cover
The frame stays 16:9 on every screen, so a wide desktop still often loses its subject on a phone. **Mobile cover image** gives small screens their own crop.
{% endstep %}
{% step %}
### Fill in the alt text
**Video alt text** describes the video for screen readers and for anyone whose connection drops the embed. One plain sentence is enough.
{% endstep %}
{% endstepper %}
{% hint style="warning" %}
**Two video fields, one winner.** If you fill both **Video** and **Video URL**, the section plays the Shopify-hosted file and ignores the URL — silently, with nothing in the editor to tell you. If your YouTube embed isn't showing, the uploaded file is almost always the reason. Clear the **Video** field and the URL takes over.
{% endhint %}
{% hint style="success" icon="lightbulb" %}
### Good to know
* **The frame is locked to 16:9.** There is no ratio setting. A vertical or square video will be letterboxed inside a widescreen frame — for vertical footage, use **Stories Slideshow** or a **Loop video** block instead.
* **Click to play, always.** This is not a background video section: the cover sits there until the visitor presses play. If you want motion that starts on its own, that's the **Video Banner** in the Banners group or a **Loop video** block.
* **A Shopify-hosted video plays with sound and native controls.** Visitors can scrub, pause and mute it themselves — which is exactly what you want for a film someone chose to watch.
* **The cover falls back in a chain.** **Cover image** → **Mobile cover image** → the video's own preview frame → a theme placeholder. You'll never get a black box, but you also won't get a considered first frame unless you upload one.
* **An empty section vanishes on the live store.** With both video fields blank the section still shows in the editor, so it's easy to publish a page where it simply isn't there. Preview on the live storefront before you call it done.
* **Enable video looping** restarts the clip when it reaches the end — good for a short atmospheric piece, distracting for anything with a narrative.
* **Two colour schemes, not one.** **Color scheme** paints the area around the video; **Video color scheme** paints the frame itself. They default to different schemes on purpose.
{% endhint %}
### Customization ideas
The brand film, placed where it earns its keep
Put the section halfway down the homepage, after the first collection row — people who have scrolled that far are the ones willing to watch two minutes about you. A hero-position video mostly gets scrolled past.
Product demo on the product template
Add the section to the product template below the buy button, with a cover still showing the product mid-use. It answers the "how does this actually work" question that otherwise becomes a support email.
Looping lookbook
A 10–15 second clip with **Enable video looping** on, cover image styled like the rest of your photography. It reads as a moving editorial image rather than as a video to commit to.
Press or testimonial reel
A cut of customer clips or press coverage, placed directly above your reviews section so the social proof arrives as one block rather than two.
***
### Settings reference
Section settings
| Setting | What it does |
| -------------------- | ---------------------------------------------------------------------------------- |
| Enable video looping | Restarts the video when it reaches the end. |
| Video | A video file hosted by Shopify. **Takes precedence over Video URL.** |
| Video URL | A YouTube or Vimeo link. Pre-filled with a sample link — replace it. |
| Cover image | The frame shown before playback starts. |
| Mobile cover image | Separate cover for small screens. Also used as a fallback if Cover image is empty. |
| Video alt text | Description for screen readers and failed embeds. |
**Background animation** — the standard Volume animation group: animation mode, on-scroll behaviour and its speed and zoom settings, with a separate toggle for mobile.
**Section layout** — full width, grid, bottom line and framing, as in every other Volume section.
**Color**
| Setting | What it does |
| ------------------ | --------------------------------------------------------------------------------- |
| Color scheme | Scheme for the section around the video. Defaults to the first background scheme. |
| Video color scheme | Scheme for the video frame itself. Defaults to the second background scheme. |
**Spacing** — top and bottom spacing multipliers and inner padding.
### Best practices
* **Keep it under 90 seconds.** Completion rates fall off a cliff after that, and a visitor who abandons a video usually abandons the page with it.
* **Put a face on the cover.** Covers with a person in them get pressed far more often than covers showing a product alone or, worst of all, a frame of text.
* **Decide where the video lives for a reason.** YouTube brings its own branding and its own "watch next" suggestions; a Shopify-hosted file brings neither, but you carry the bandwidth and the file size limits.
* **Don't make it the first thing on the page.** The cover image still has to load, and a video section at the very top of a template is a slower first impression than a banner.
## Related
* [Media with Text](/docs/volume-themes/sections/media/media-with-text.md) — when the video needs copy and a button beside it
* [Image Slideshow & Stories Slideshow](/docs/volume-themes/sections/media/image-slideshow-and-stories-slideshow.md) — for vertical, story-format video
* [Multicolumn](/docs/volume-themes/sections/media/multicolumn.md) — for several short looping clips side by side
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://staylime.com/docs/volume-themes/sections/media/video.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
