From f0f922ee7081964afa518d4edc768a77e421218b Mon Sep 17 00:00:00 2001
From: Constantine Nathanson <constantine@cloudinary.com>
Date: Thu, 20 Aug 2026 15:34:07 +0300
Subject: [PATCH] docs: split transform-and-deliver into image and video pairs

The doc covered both images and video, but the only runnable example was
image-only, so cloudinary.video() was documented and never demonstrated.

- rename transform-and-deliver-media.md to transform-and-deliver-image.md and
  drop its Video section
- add docs/transform-and-deliver-video.md and
  examples/transform-and-deliver-video.js covering the player tag, video URL,
  poster frame, and HLS streaming
- split the delivery row in platform-capabilities.md by media type, and update
  both task indexes and the remaining cross-references

URLs verified against the demo cloud: the mp4, poster-frame jpg, and m3u8
manifest all return 200.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 README.md                                     |   3 +-
 docs/README.md                                |   3 +-
 docs/platform-capabilities.md                 |   5 +-
 ...edia.md => transform-and-deliver-image.md} |  19 +--
 docs/transform-and-deliver-video.md           | 109 ++++++++++++++++++
 docs/troubleshoot-errors.md                   |   3 +-
 docs/upload-image.md                          |   2 +-
 docs/upload-large-video.md                    |   2 +
 examples/transform-and-deliver-image.js       |   3 +-
 examples/transform-and-deliver-video.js       |  74 ++++++++++++
 10 files changed, 202 insertions(+), 21 deletions(-)
 rename docs/{transform-and-deliver-media.md => transform-and-deliver-image.md} (87%)
 create mode 100644 docs/transform-and-deliver-video.md
 create mode 100644 examples/transform-and-deliver-video.js

diff --git a/README.md b/README.md
index 242f4388..2a24ac73 100644
--- a/README.md
+++ b/README.md
@@ -61,7 +61,8 @@ Save as `quickstart.js` and run `node quickstart.js`. [Create a free account](ht
 - [Upload an image](docs/upload-image.md)
 - [Upload a large video](docs/upload-large-video.md)
 - [Sign a browser upload](docs/sign-browser-upload.md)
-- [Transform and deliver media](docs/transform-and-deliver-media.md)
+- [Transform and deliver an image](docs/transform-and-deliver-image.md)
+- [Transform and deliver a video](docs/transform-and-deliver-video.md)
 - [Search and manage assets](docs/search-and-manage-assets.md)
 - [Moderate an upload](docs/moderate-upload.md)
 - [Use structured metadata](docs/use-structured-metadata.md)
diff --git a/docs/README.md b/docs/README.md
index 6aa49a02..a6350236 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -29,7 +29,8 @@ failures. Runnable versions of most tasks are in `node_modules/cloudinary/exampl
 - [Upload an image](upload-image.md)
 - [Upload a large video](upload-large-video.md)
 - [Sign a browser upload](sign-browser-upload.md)
-- [Transform and deliver media](transform-and-deliver-media.md)
+- [Transform and deliver an image](transform-and-deliver-image.md)
+- [Transform and deliver a video](transform-and-deliver-video.md)
 - [Search and manage assets](search-and-manage-assets.md)
 - [Moderate an upload](moderate-upload.md)
 - [Use structured metadata](use-structured-metadata.md)
diff --git a/docs/platform-capabilities.md b/docs/platform-capabilities.md
index c157d5d4..db6dd34d 100644
--- a/docs/platform-capabilities.md
+++ b/docs/platform-capabilities.md
@@ -79,8 +79,9 @@ Cloudinary publishes agent-readable indexes. Fetch these instead of guessing at
 
 | To do this | Use | Where to go |
 |---|---|---|
-| Build a resize, crop, overlay, or format-optimized URL | `url`, `image`, `video` | [Transform and deliver media](transform-and-deliver-media.md) |
-| Apply generative edits (gen fill, background removal, ...) | `effect` / `raw_transformation` — **generic strings only, no typed builders** | [Transform and deliver media](transform-and-deliver-media.md) |
+| Build a resize, crop, overlay, or format-optimized image URL | `url`, `image` | [Transform and deliver an image](transform-and-deliver-image.md) |
+| Build a video URL, player tag, poster frame, or HLS/DASH stream | `url` (with `resource_type: 'video'`), `video` | [Transform and deliver a video](transform-and-deliver-video.md) |
+| Apply generative edits (gen fill, background removal, ...) | `effect` / `raw_transformation` — **generic strings only, no typed builders** | [Transform and deliver an image](transform-and-deliver-image.md) |
 
 URL building is local: no network call, no `api_secret`.
 
diff --git a/docs/transform-and-deliver-media.md b/docs/transform-and-deliver-image.md
similarity index 87%
rename from docs/transform-and-deliver-media.md
rename to docs/transform-and-deliver-image.md
index 62e29c58..2e7d3be0 100644
--- a/docs/transform-and-deliver-media.md
+++ b/docs/transform-and-deliver-image.md
@@ -1,11 +1,13 @@
-# Transform and deliver media
+# Transform and deliver an image
 
 ## When to use
 
-Generate CDN-backed delivery URLs that resize, crop, overlay, or optimize images and video. URL
+Generate CDN-backed delivery URLs that resize, crop, overlay, or optimize an image. URL
 generation is local — no network call, no secret required — and the derived asset is
 created by Cloudinary on first request, then served from CDN cache.
 
+For video, see [Transform and deliver a video](transform-and-deliver-video.md).
+
 ## Optimized image URL
 
 ```js
@@ -52,18 +54,6 @@ console.log(bannerUrl);
 Reordering components changes the output. When matching eagerly generated versions,
 the serialized transformation string must match exactly.
 
-## Video
-
-```js
-// 'examples/uploaded-large-video' is created by the "Upload a large video" task
-const clip = cloudinary.video('examples/uploaded-large-video', {
-  width: 640,
-  crop: 'scale',
-  quality: 'auto',
-  controls: true
-}); // returns an HTML <video> tag; cloudinary.url(..., {resource_type: 'video'}) returns just the URL
-```
-
 ## Generative editing on delivery
 
 Server-supported generative transformations (background removal, generative fill, and
@@ -81,6 +71,7 @@ https://cloudinary.com/documentation/generative_ai_transformations.md before rel
 ## Related
 
 - Runnable example: `examples/transform-and-deliver-image.js`
+- [Transform and deliver a video](transform-and-deliver-video.md)
 - Every transformation parameter and its accepted values:
   [Transformation reference](https://cloudinary.com/documentation/transformation_reference.md)
 - [Image manipulation guide](https://cloudinary.com/documentation/node_image_manipulation.md)
diff --git a/docs/transform-and-deliver-video.md b/docs/transform-and-deliver-video.md
new file mode 100644
index 00000000..755f3dd3
--- /dev/null
+++ b/docs/transform-and-deliver-video.md
@@ -0,0 +1,109 @@
+# Transform and deliver a video
+
+## When to use
+
+Generate CDN-backed delivery URLs and player markup for a video that is already in
+Cloudinary. URL generation is local — no network call, no secret required — and the
+derived asset is created by Cloudinary on first request, then served from CDN cache.
+
+For images, see [Transform and deliver an image](transform-and-deliver-image.md).
+
+## Player markup
+
+`cloudinary.video()` returns a complete HTML `<video>` tag, not a URL:
+
+```js
+const cloudinary = require('cloudinary').v2; // only cloud_name is needed for URL generation
+
+// 'examples/uploaded-large-video' is created by the "Upload a large video" task
+const tag = cloudinary.video('examples/uploaded-large-video', {
+  width: 640,
+  crop: 'scale',
+  quality: 'auto',
+  controls: true,
+  secure: true
+});
+console.log(tag);
+// <video controls poster='.../c_scale,q_auto,w_640/<id>.jpg' width='640'>
+//   <source src='.../<id>.webm' type='video/webm'>
+//   <source src='.../<id>.mp4'  type='video/mp4'>
+//   <source src='.../<id>.ogv'  type='video/ogg'>
+// </video>
+```
+
+The tag carries three `<source>` variants so the browser picks a format it supports, plus
+a generated JPG poster frame. Drop it into a template as-is.
+
+## Video URL only
+
+`cloudinary.video()` returns markup; for the URL alone use `cloudinary.url()` with
+`resource_type: 'video'`.
+
+```js
+const videoUrl = cloudinary.url('examples/uploaded-large-video', {
+  resource_type: 'video',
+  width: 640,
+  crop: 'scale',
+  quality: 'auto',
+  secure: true
+});
+// https://res.cloudinary.com/<cloud>/video/upload/c_scale,q_auto,w_640/examples/uploaded-large-video
+```
+
+## Thumbnail from a video frame
+
+Request an image format from a video asset to get a still. `start_offset` picks the
+second to grab:
+
+```js
+const posterUrl = cloudinary.url('examples/uploaded-large-video', {
+  resource_type: 'video',
+  format: 'jpg',
+  start_offset: '2',   // so_2 — two seconds in
+  width: 400,
+  crop: 'fill',
+  secure: true
+});
+// https://res.cloudinary.com/<cloud>/video/upload/c_fill,so_2,w_400/examples/uploaded-large-video.jpg
+```
+
+## Adaptive bitrate streaming
+
+For anything longer than a short clip, deliver HLS or DASH rather than a single MP4 so
+the player can switch renditions:
+
+```js
+const hlsUrl = cloudinary.url('examples/uploaded-large-video', {
+  resource_type: 'video',
+  streaming_profile: 'hd',   // sp_hd
+  format: 'm3u8',            // .mpd for DASH
+  secure: true
+});
+// https://res.cloudinary.com/<cloud>/video/upload/sp_hd/examples/uploaded-large-video.m3u8
+```
+
+Streaming profiles are per-environment; list the available ones with
+`cloudinary.api.list_streaming_profiles()`.
+
+## Cache behavior
+
+- The same URL is served from CDN cache; a new transformation means a new URL.
+- To bust stale caches after re-uploading, deliver with the asset `version` from the
+  upload response (`cloudinary.url(id, { resource_type: 'video', version: result.version })`).
+
+## Troubleshooting
+
+- The asset was uploaded with `upload_large` and will not transform or stream — it landed
+  as `raw`. Re-upload with `resource_type: 'video'`. See
+  [Upload a large video](upload-large-video.md).
+- The first request for a new transformation is slow — the derived video is being
+  generated. For long jobs prefer `eager_async` with a `notification_url` over polling.
+
+## Related
+
+- Runnable example: `examples/transform-and-deliver-video.js`
+- [Transform and deliver an image](transform-and-deliver-image.md)
+- [Upload a large video](upload-large-video.md)
+- Every transformation parameter and its accepted values:
+  [Transformation reference](https://cloudinary.com/documentation/transformation_reference.md)
+- [Video manipulation guide](https://cloudinary.com/documentation/node_video_manipulation.md)
diff --git a/docs/troubleshoot-errors.md b/docs/troubleshoot-errors.md
index 42b2db5c..cc568343 100644
--- a/docs/troubleshoot-errors.md
+++ b/docs/troubleshoot-errors.md
@@ -72,7 +72,8 @@ chunked upload; chunks retry independently.
 ### Stale delivery after re-upload
 CDN-cached URLs do not update instantly. Deliver with the new `version` from the upload
 response, which changes the URL immediately. See
-[Transform and deliver media](transform-and-deliver-media.md).
+[Transform and deliver an image](transform-and-deliver-image.md) or
+[a video](transform-and-deliver-video.md).
 
 ## Still stuck
 
diff --git a/docs/upload-image.md b/docs/upload-image.md
index 7daae4b5..dc5ae3b0 100644
--- a/docs/upload-image.md
+++ b/docs/upload-image.md
@@ -81,5 +81,5 @@ it before uploading, or upgrade the plan.
 ## Related
 
 - Runnable example: `examples/upload-image.js`
-- [Transform and deliver media](transform-and-deliver-media.md)
+- [Transform and deliver an image](transform-and-deliver-image.md)
 - [Upload guide](https://cloudinary.com/documentation/node_image_and_video_upload.md)
diff --git a/docs/upload-large-video.md b/docs/upload-large-video.md
index f1cf8127..3ff463ae 100644
--- a/docs/upload-large-video.md
+++ b/docs/upload-large-video.md
@@ -91,4 +91,6 @@ webhook; the response then includes a pending status until Cloudinary calls your
 
 - Runnable example: `examples/upload-large-video.js` — works with no arguments; it
   downloads a sample video from the Cloudinary demo account if none is supplied.
+- [Transform and deliver a video](transform-and-deliver-video.md) — what to do with it
+  once it is uploaded.
 - [Video upload guide](https://cloudinary.com/documentation/node_image_and_video_upload.md#node_js_video_upload)
diff --git a/examples/transform-and-deliver-image.js b/examples/transform-and-deliver-image.js
index 0302b668..fd8b73a6 100644
--- a/examples/transform-and-deliver-image.js
+++ b/examples/transform-and-deliver-image.js
@@ -7,7 +7,8 @@
  * In your own project: const cloudinary = require('cloudinary').v2;
  *
  * Related:
- * - Task doc: docs/transform-and-deliver-media.md
+ * - Task doc: docs/transform-and-deliver-image.md
+ * - For video: examples/transform-and-deliver-video.js
  * - Every transformation parameter and its accepted values:
  *   https://cloudinary.com/documentation/transformation_reference.md
  * - Building transformations from a plain-language description: the
diff --git a/examples/transform-and-deliver-video.js b/examples/transform-and-deliver-video.js
new file mode 100644
index 00000000..2604abb0
--- /dev/null
+++ b/examples/transform-and-deliver-video.js
@@ -0,0 +1,74 @@
+/**
+ * Build transformation and delivery URLs for a video already in Cloudinary.
+ *
+ * URL generation is local - no network call and no credentials beyond the cloud name.
+ * The derived asset is created by Cloudinary on first request and then served from CDN cache.
+ *
+ * In your own project: const cloudinary = require('cloudinary').v2;
+ *
+ * Related:
+ * - Task doc: docs/transform-and-deliver-video.md
+ * - For images: examples/transform-and-deliver-image.js
+ * - Every transformation parameter and its accepted values:
+ *   https://cloudinary.com/documentation/transformation_reference.md
+ * - Building transformations from a plain-language description: the
+ *   cloudinary-transformations skill (npx skills add cloudinary-devs/skills)
+ */
+const cloudinary = require('../cloudinary').v2;
+
+function main(publicId = 'dog') {
+  // A complete <video> tag: three <source> variants plus a generated poster frame.
+  const playerTag = cloudinary.video(publicId, {
+    width: 640,
+    crop: 'scale',
+    quality: 'auto',
+    controls: true,
+    secure: true
+  });
+
+  // The delivery URL on its own, for a player you control.
+  const videoUrl = cloudinary.url(publicId, {
+    resource_type: 'video',
+    width: 640,
+    crop: 'scale',
+    quality: 'auto',
+    secure: true
+  });
+
+  // A still frame as an image: ask a video asset for an image format.
+  const posterUrl = cloudinary.url(publicId, {
+    resource_type: 'video',
+    format: 'jpg',
+    start_offset: '2',
+    width: 400,
+    crop: 'fill',
+    secure: true
+  });
+
+  // Adaptive bitrate streaming - prefer this over a single MP4 for long videos.
+  const hlsUrl = cloudinary.url(publicId, {
+    resource_type: 'video',
+    streaming_profile: 'hd',
+    format: 'm3u8',
+    secure: true
+  });
+
+  console.log(`Video URL (640 wide):     ${videoUrl}`);
+  console.log(`Poster frame at 2s:       ${posterUrl}`);
+  console.log(`HLS adaptive streaming:   ${hlsUrl}`);
+  console.log(`Player tag:               ${playerTag}`);
+  return { playerTag, videoUrl, posterUrl, hlsUrl };
+}
+
+if (require.main === module) {
+  try {
+    main(process.argv[2]);
+  } catch (error) {
+    const { message } = error.error || error;
+    console.error(`URL generation failed: ${message}`);
+    console.error('Check that cloud_name is configured (CLOUDINARY_URL or cloudinary.config()).');
+    process.exitCode = 1;
+  }
+}
+
+module.exports = { main };