@spree/docs 0.1.165 → 0.1.167

package/dist/developer/core-concepts/media.md

@@ -1,7 +1,7 @@
 ---
 title: Media
 sidebarTitle: "Media"
-description: Manage product media in Spree — images, videos, named variants, focal points, and how media is uploaded, resized, and served via the Store API.
+description: Manage product media in Spree — images, hosted and external video, named variants, focal points, and how media is uploaded, resized, and served via the Store API.
 ---
 
 import { Since } from '/snippets/since.mdx';
@@ -106,6 +106,99 @@ The Store API's `media` field on a product returns its gallery — product-level
 
 This dual rendering means existing storefronts keep working during the upgrade; new uploads attach to the product, and you opt into a [one-shot migration](../upgrades/5.4-to-5.5.md) to re-home legacy variant-pinned data when convenient.
 
+### Video 
+
+A product gallery can hold video as well as images. Spree supports both ways merchants usually have it:
+
+| `media_type` | What it is | What it needs |
+|---|---|---|
+| `video` | A video file you upload, served from your own storage | An uploaded file (MP4, WebM, or QuickTime) |
+| `external_video` | A YouTube or Vimeo link | The link, in `external_video_url` |
+
+Spree reads the link once, when it is saved, and rejects anything it cannot embed — so a broken URL is caught at the point a merchant enters it rather than in the storefront. What it derives comes back on the media object:
+
+| Field | Description |
+|---|---|
+| `video_provider` | `youtube` or `vimeo` |
+| `video_embed_url` | Player URL, ready for an `iframe` |
+| `video_url` | The uploaded file itself, for hosted video |
+| `poster_url` | A still frame for the video |
+
+Because the derived fields are on the response, a storefront embeds a video without parsing links itself.
+
+#### Adding an external video
+
+
+```typescript Admin SDK
+const video = await client.products.media.create('prod_86Rf07xd4z', {
+  media_type: 'external_video',
+  external_video_url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
+  alt: 'How it is made',
+})
+
+video.video_embed_url // https://www.youtube.com/embed/dQw4w9WgXcQ
+```
+
+```bash cURL
+curl -X POST 'https://api.mystore.com/api/v3/admin/products/prod_86Rf07xd4z/media' \
+  -H 'X-Spree-API-Key: sk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "media_type": "external_video",
+    "external_video_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
+    "alt": "How it is made"
+  }'
+```
+
+
+#### Uploading a video file
+
+A hosted video is uploaded the same way an image is, with `media_type` telling Spree what it is. Add `poster_signed_id` to give it a still frame:
+
+```typescript Admin SDK
+const video = await client.products.media.create('prod_86Rf07xd4z', {
+  media_type: 'video',
+  signed_id: signedVideoBlobId,
+  poster_signed_id: signedPosterBlobId,
+  alt: 'Product in use',
+})
+```
+
+A poster can also be added or replaced later, on its own:
+
+```typescript Admin SDK
+await client.products.media.update('prod_86Rf07xd4z', 'media_k5nR8xLq', {
+  poster_signed_id: signedPosterBlobId,
+})
+```
+
+> **INFO:** Spree serves an uploaded video as you uploaded it — it does not transcode. Keep files web-friendly (H.264 MP4 or WebM) so they play everywhere, and prefer an external video for long footage so the provider handles streaming.
+
+#### Posters
+
+A video has no image of its own, so its sized URLs (`small_url`, `large_url`, and the rest) resolve to its **poster** — the still shown before the video plays. A gallery that only knows how to draw an image still renders the right picture, and can play the video when the shopper asks for it.
+
+Where the poster comes from, in order:
+
+1. **The one the merchant uploaded** — `poster_signed_id` on write, editable in the dashboard's media editor.
+2. **The provider's own still**, for a YouTube link.
+3. **Nothing**, for a Vimeo link or an uploaded file with no poster — the tile falls back to a placeholder.
+
+Spree does not extract a frame from an uploaded video, so give hosted video and Vimeo links a poster if you want them to show a still.
+
+### Focal Point 
+
+`focal_point_x` and `focal_point_y` mark the part of an image that must stay in frame when a storefront crops it to a different shape. Both are fractions between 0 and 1, measured from the top left, so `{ x: 0.5, y: 0.5 }` is dead centre — which is also what a storefront should assume when they are null.
+
+```typescript Admin SDK
+await client.products.media.update('prod_86Rf07xd4z', 'media_k5nR8xLq', {
+  focal_point_x: 0.25,
+  focal_point_y: 0.4,
+})
+```
+
+Spree stores the focal point and serves it; the cropping itself is the storefront's decision, since only it knows the shape it needs.
+
 ### Named Variant Sizes 
 
 When an image is uploaded, Spree automatically generates optimized versions in the background:
@@ -226,6 +319,10 @@ curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=media,vari
 | `focal_point_x` | number \| null | Horizontal focal point (0.0–1.0) |
 | `focal_point_y` | number \| null | Vertical focal point (0.0–1.0) |
 | `external_video_url` | string \| null | External video URL (YouTube/Vimeo) |
+| `video_provider` | string \| null | `youtube` or `vimeo`, derived from the link  |
+| `video_embed_url` | string \| null | Embeddable player URL, derived from the link  |
+| `video_url` | string \| null | Uploaded video file URL  |
+| `poster_url` | string \| null | Still frame for a video  |
 | `original_url` | string \| null | Full-size image URL (inline disposition) |
 | `mini_url` ... `xlarge_url` | string \| null | Named variant URLs |
 | `download_url` | string \| null | Same blob as `original_url` but with `Content-Disposition: attachment`. Admin API only.  |
@@ -255,6 +352,7 @@ Spree supports two storage service types:
 - **Always provide alt text** for accessibility and SEO
 - **Use named variant sizes** (`mini`, `small`, `medium`, `large`, `xlarge`) for optimal performance
 - **Use a CDN** in production for faster delivery
+- **Give every video a poster** so a gallery has something to show before playback
 
 ## Related Documentation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spree/docs",
-  "version": "0.1.165",
+  "version": "0.1.167",
   "description": "Spree Commerce developer documentation for AI agents and local reference",
   "type": "module",
   "license": "CC-BY-4.0",