From 2e4e61647dc9ba5420b70a6efcbb56a92f5f195e Mon Sep 17 00:00:00 2001 From: Taylor Smith Date: Tue, 4 Mar 2025 15:46:48 -0600 Subject: [PATCH 1/6] [Stream] Documentation edits --- .../2025-03-06-media-transformations.mdx | 24 +++ .../docs/stream/transform-videos/index.mdx | 155 ++++++++++++++++++ 2 files changed, 179 insertions(+) create mode 100644 src/content/changelog/stream/2025-03-06-media-transformations.mdx create mode 100644 src/content/docs/stream/transform-videos/index.mdx diff --git a/src/content/changelog/stream/2025-03-06-media-transformations.mdx b/src/content/changelog/stream/2025-03-06-media-transformations.mdx new file mode 100644 index 000000000000000..33822332ab66b14 --- /dev/null +++ b/src/content/changelog/stream/2025-03-06-media-transformations.mdx @@ -0,0 +1,24 @@ +--- +title: Introducing Media Transformations from Cloudflare Stream +description: > + Dynamically optimize, clip, and resize video from any origin, no storage + migration needed. +date: 2025-03-06T12:00:00Z +--- + +For customers with a huge volume of short video — generative AI output, +e-commerce product videos, social media clips, or short marketing content — +uploading those assets to Stream is not always practical. Further, Stream's key +features like adaptive bitrate encoding and HLS packaging offer diminishing +returns on short content or small files. + +Instead, with Media Transformations, content like this can fetched from +customers' existing storage like R2 or S3 directly, optimized quickly, and +delivered efficiently as small MP4 files. Cloudflare Images customers reading +this will note that this sounds just like their existing Image Transformation +workflows. Starting today, the same workflow can be applied to your short-form +videos. + +(( PLACEHOLDER DEMO )) + +For more information, learn about [Transforming Videos](/stream/transform-videos/). diff --git a/src/content/docs/stream/transform-videos/index.mdx b/src/content/docs/stream/transform-videos/index.mdx new file mode 100644 index 000000000000000..ba8d4d7b1e992eb --- /dev/null +++ b/src/content/docs/stream/transform-videos/index.mdx @@ -0,0 +1,155 @@ +--- +pcx_content_type: concept +title: Transform videos +sidebar: + order: 5 + +--- + +Media Transformations let you optimize and manipulate videos stored _outside_ of +the Cloudflare Stream product. Transformed videos and images are served from one +of your zones on Cloudflare. + +To transform a video or image, you must enable transformations for your zone. If +your zone already has Image Transformations enabled, then it is ready to optimize +videos with Media Transformations, too. + +## Getting started + +You can dynamically optimize and generate still images from videos that +are stored _outside_ of Cloudflare Stream with Media Transforamtions. + +Cloudflare will automatically cache every transformed video or image on our +global network so that you store only the original image at your origin. + +To enable transformations on your zone: + +- Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login) and select your account. +- Go to **Stream** > **Transformations**. +- Locate the specific zone where you want to enable transformations. +- Select **Enable** for zone. + +## Transform a video by URL + +You can convert and resize videos by requesting them via a specially-formatted URL, +without writing any code. The URL format is: + +``` +https://example.com/media// +``` + +- `example.com` + - Your website or zone on Cloudflare, with Transformations enabled +- `/cdn-cgi/media/` + - A prefix that identifies that this is a special path handled by Cloudflare's + built-in media transformation service. +- `` + - A comma-separated list of options. See available options below. +- `` + - An absolute path on the origin server or a full URL (starting with `https://` + or `http://`) of the original asset to resize. + +For example, this URL will source an HD video from an R2 bucket, shorten it, crop +and resize it as a square, and remove the audio. + +``` +https://example.com/media/mode=video,time=5s,duration=5s,width=500,height=500,fit=crop,audio=false/https://pub-8613b7f94d6146408add8fefb52c52e8.r2.dev/aus-mobile-demo.mp4 +``` + +The result is an MP4 that can be used in an HTML video element without a player library. + +### Options + +#### `mode` + +Specify the kind of output to generate. + +- `video` — output an (H.264/AAC) optimized MP4 file +- `frame` — output a still image +- `spritesheet` — output a JPEG with multiple frames + +#### `time` + +When, in the input file, to start extracting the output. Depends on `mode`: + +- When `mode` is `spritesheet` or `video`, the timestamp where the output will start +- When `mode` is `frame`, the timestamp from which to extract the still image +- Format as a time string, e.g.: 5s, 2m +- Acceptable range: 0 – 30s +- Default: 0 + +#### `duration` + +The duration of the output video or spritesheet. Depends on `mode`: + +- When `mode` is `video`, the duration of the output. +- When `mode` is `spritesheet`, the time range from which to select frames. + +#### `fit` + +In combination with `width` and `height`, how to resize and crop the output. In +the event the output is resized, it will always resize proportionally so content +is not stretched. + +- `contain` — Respecting aspect ratio, scale a video up or down to be entirely + contained within output dimensions. +- `scale-down` — Same as contain, but downscale to fit only. Do not upscale. +- `cover` — Respecting aspect ratio, scale a video up or down to entirely cover + the output dimensions, with a center-weighted crop of the remainder. + +#### `height` + +Specifies maximum height of the output in pixels. Exact behavior depends on `fit`. + +- Acceptable range: 10 - 2000 pixels + +#### `width` + +Specifies maximum width of the image in pixels. Exact behavior depends on `fit`. + +- Acceptable range: 10 - 2000 pixels + +#### `audio` + +When `mode` is `video`, specifies whether or not to include the source audio in +the output. + +- true — include source audio +- false — output will be silent +- Default: true + +#### `format` + +If `mode` is `frame`, specifies image output format. + +- Acceptable options: jpg, png + +### Source video requirements + +Input video must be less than 40MB. Please contact Stream if this input +limitation is not acceptable. + +Input video should be an MP4 with H.264 encoded video and AAC or MP3 encoded +audio. Other formats may work but are untested. + +## Limitations + +Media Transformations is currently in beta. During this period: + +- Transformations are available for all enabled zones free-of-charge. +- Restricting allowed origins for transformations is coming soon. +- Outputs from Media Transformations will be cached, but in the event they must + be regenerated, the origin fetch is not cached and may result in subsequent + requests to the origin asset. + +## Pricing + +Media Transformations will be free for all customers while in beta. + +After that, Media Transforamtions and Image Transformations will use the same +subscriptions and usage metrics. Generating a still frame (single image) from a +video counts as 1 transformation. Generating an optimized video counts as 1 +transformation _per second of the output_ video. Each unique transformation is +only billed once per month. All Media and Image Transformations cost $0.50 per +1,000 monthly unique transformation operations, with a free monthly allocation +of 5,000. From 7d8c1d82daacce0ddd65d2eeaaec883d5aa0e283 Mon Sep 17 00:00:00 2001 From: Taylor Smith Date: Tue, 4 Mar 2025 16:18:53 -0600 Subject: [PATCH 2/6] Update src/content/docs/stream/transform-videos/index.mdx Co-authored-by: hyperlint-ai[bot] <154288675+hyperlint-ai[bot]@users.noreply.github.com> --- src/content/docs/stream/transform-videos/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/stream/transform-videos/index.mdx b/src/content/docs/stream/transform-videos/index.mdx index ba8d4d7b1e992eb..4b6a4436781ed2e 100644 --- a/src/content/docs/stream/transform-videos/index.mdx +++ b/src/content/docs/stream/transform-videos/index.mdx @@ -74,7 +74,7 @@ When, in the input file, to start extracting the output. Depends on `mode`: - When `mode` is `spritesheet` or `video`, the timestamp where the output will start - When `mode` is `frame`, the timestamp from which to extract the still image -- Format as a time string, e.g.: 5s, 2m +- Format as a time string, for example: 5s, 2m - Acceptable range: 0 – 30s - Default: 0 From bb9f9cbb633f7af7a9bef877e812c754efda39ee Mon Sep 17 00:00:00 2001 From: Taylor Smith Date: Tue, 4 Mar 2025 16:45:42 -0600 Subject: [PATCH 3/6] [Stream] Tweaks --- .../2025-03-06-media-transformations.mdx | 28 +++++++++++++------ .../docs/stream/transform-videos/index.mdx | 7 +++-- 2 files changed, 23 insertions(+), 12 deletions(-) diff --git a/src/content/changelog/stream/2025-03-06-media-transformations.mdx b/src/content/changelog/stream/2025-03-06-media-transformations.mdx index 33822332ab66b14..5cf046e636fdcba 100644 --- a/src/content/changelog/stream/2025-03-06-media-transformations.mdx +++ b/src/content/changelog/stream/2025-03-06-media-transformations.mdx @@ -6,18 +6,28 @@ description: > date: 2025-03-06T12:00:00Z --- +Today, we are thrilled to announce Media Transformations, a new service that +brings the magic of [Image Transformations](/images/transform-images/) to +_short-form video files,_ wherever they are stored! + For customers with a huge volume of short video — generative AI output, e-commerce product videos, social media clips, or short marketing content — -uploading those assets to Stream is not always practical. Further, Stream's key -features like adaptive bitrate encoding and HLS packaging offer diminishing -returns on short content or small files. +uploading those assets to Stream is not always practical. Sometimes, the +greatest friction to getting started was the thought of all that migrating. +Customers want a simpler solution that retains their current storage strategy to +deliver small, optimized MP4 files. Now you can do that with Media +Transformations. + +To transform a video or image, +[enable transformations](/stream/transform-videos/#getting-started) for your +zone, then make a simple request with a specially formatted URL. The result is +an MP4 that can be used in an HTML video element without a player library. +If your zone already has Image Transformations enabled, then it is ready to +optimize videos with Media Transformations, too. -Instead, with Media Transformations, content like this can fetched from -customers' existing storage like R2 or S3 directly, optimized quickly, and -delivered efficiently as small MP4 files. Cloudflare Images customers reading -this will note that this sounds just like their existing Image Transformation -workflows. Starting today, the same workflow can be applied to your short-form -videos. +``` text title="URL format" +https://example.com/media// +``` (( PLACEHOLDER DEMO )) diff --git a/src/content/docs/stream/transform-videos/index.mdx b/src/content/docs/stream/transform-videos/index.mdx index ba8d4d7b1e992eb..b7b2f4f37064056 100644 --- a/src/content/docs/stream/transform-videos/index.mdx +++ b/src/content/docs/stream/transform-videos/index.mdx @@ -10,9 +10,10 @@ Media Transformations let you optimize and manipulate videos stored _outside_ of the Cloudflare Stream product. Transformed videos and images are served from one of your zones on Cloudflare. -To transform a video or image, you must enable transformations for your zone. If -your zone already has Image Transformations enabled, then it is ready to optimize -videos with Media Transformations, too. +To transform a video or image, you must +[enable transformations](/stream/transform-videos/#getting-started) +for your zone. If your zone already has Image Transformations enabled, then it +is ready to optimize videos with Media Transformations, too. ## Getting started From 061208a89ce8ff6fe8ef9958b7cccb3b6c685079 Mon Sep 17 00:00:00 2001 From: Taylor Smith Date: Wed, 5 Mar 2025 11:14:12 -0600 Subject: [PATCH 4/6] Placeholder changelog demo --- .../stream/2025-03-06-media-transformations.mdx | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/src/content/changelog/stream/2025-03-06-media-transformations.mdx b/src/content/changelog/stream/2025-03-06-media-transformations.mdx index 5cf046e636fdcba..5018ad2c36fa9c2 100644 --- a/src/content/changelog/stream/2025-03-06-media-transformations.mdx +++ b/src/content/changelog/stream/2025-03-06-media-transformations.mdx @@ -29,6 +29,18 @@ optimize videos with Media Transformations, too. https://example.com/media// ``` -(( PLACEHOLDER DEMO )) +For example, we have a short video of the mobile in Austin's office. The +original is nearly 30 megabytes and wider than necessary for this layout. +Consider a simple width adjustment: + + + +(( REPEAT URL )) + +The result is less than 3 megabytes, properly sized, and delivered dynamically +so that customers do not have to manage the creation and storage of these +transformed assets. For more information, learn about [Transforming Videos](/stream/transform-videos/). From 882cecaf801924d0771472e40e856b06f0dd47df Mon Sep 17 00:00:00 2001 From: Taylor Smith Date: Wed, 5 Mar 2025 13:01:45 -0600 Subject: [PATCH 5/6] URL fixes --- .../stream/2025-03-06-media-transformations.mdx | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/src/content/changelog/stream/2025-03-06-media-transformations.mdx b/src/content/changelog/stream/2025-03-06-media-transformations.mdx index 5018ad2c36fa9c2..8eb85b5f4a38d59 100644 --- a/src/content/changelog/stream/2025-03-06-media-transformations.mdx +++ b/src/content/changelog/stream/2025-03-06-media-transformations.mdx @@ -26,7 +26,7 @@ If your zone already has Image Transformations enabled, then it is ready to optimize videos with Media Transformations, too. ``` text title="URL format" -https://example.com/media// +https://example.com/cdn-cgi/media// ``` For example, we have a short video of the mobile in Austin's office. The @@ -34,10 +34,13 @@ original is nearly 30 megabytes and wider than necessary for this layout. Consider a simple width adjustment: -(( REPEAT URL )) +``` text title="Example URL" +https://example.com/cdn-cgi/media/width=640/ +https://developers.cloudflare.com/cdn-cgi/media/width=640/https://pub-d9fcbc1abcd244c1821f38b99017347f.r2.dev/aus-mobile.mp4 +``` The result is less than 3 megabytes, properly sized, and delivered dynamically so that customers do not have to manage the creation and storage of these From 21214eb29a0eee01ede04ec63bfc159328ce086f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Denise=20Pe=C3=B1a?= <75506267+dcpena@users.noreply.github.com> Date: Thu, 6 Mar 2025 10:38:22 -0600 Subject: [PATCH 6/6] Line spacing and small edits --- .../docs/stream/transform-videos/index.mdx | 141 +++++++----------- 1 file changed, 58 insertions(+), 83 deletions(-) diff --git a/src/content/docs/stream/transform-videos/index.mdx b/src/content/docs/stream/transform-videos/index.mdx index 1e28c1b989fd672..a0fdcab6412cdf7 100644 --- a/src/content/docs/stream/transform-videos/index.mdx +++ b/src/content/docs/stream/transform-videos/index.mdx @@ -6,52 +6,37 @@ sidebar: --- -Media Transformations let you optimize and manipulate videos stored _outside_ of -the Cloudflare Stream product. Transformed videos and images are served from one -of your zones on Cloudflare. +Media Transformations let you optimize and manipulate videos stored _outside_ of the Cloudflare Stream. Transformed videos and images are served from one of your zones on Cloudflare. -To transform a video or image, you must -[enable transformations](/stream/transform-videos/#getting-started) -for your zone. If your zone already has Image Transformations enabled, then it -is ready to optimize videos with Media Transformations, too. +To transform a video or image, you must [enable transformations](/stream/transform-videos/#getting-started) for your zone. If your zone already has Image Transformations enabled, you can also optimize videos with Media Transformations. ## Getting started -You can dynamically optimize and generate still images from videos that -are stored _outside_ of Cloudflare Stream with Media Transforamtions. +You can dynamically optimize and generate still images from videos that are stored _outside_ of Cloudflare Stream with Media Transformations. -Cloudflare will automatically cache every transformed video or image on our -global network so that you store only the original image at your origin. +Cloudflare will automatically cache every transformed video or image on our global network so that you store only the original image at your origin. To enable transformations on your zone: -- Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login) and select your account. -- Go to **Stream** > **Transformations**. -- Locate the specific zone where you want to enable transformations. -- Select **Enable** for zone. +1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login) and select your account. +2. Go to **Stream** > **Transformations**. +3. Locate the specific zone where you want to enable transformations. +4. Select **Enable** for zone. ## Transform a video by URL -You can convert and resize videos by requesting them via a specially-formatted URL, -without writing any code. The URL format is: +You can convert and resize videos by requesting them via a specially-formatted URL, without writing any code. The URL format is: ``` https://example.com/media// ``` -- `example.com` - - Your website or zone on Cloudflare, with Transformations enabled -- `/cdn-cgi/media/` - - A prefix that identifies that this is a special path handled by Cloudflare's - built-in media transformation service. -- `` - - A comma-separated list of options. See available options below. -- `` - - An absolute path on the origin server or a full URL (starting with `https://` - or `http://`) of the original asset to resize. +- `example.com`: Your website or zone on Cloudflare, with Transformations enabled. +- `/cdn-cgi/media/`: A prefix that identifies a special path handled by Cloudflare's built-in media transformation service. +- ``: A comma-separated list of options. Refer to the available options below. +- ``: An absolute path on the origin server or a full URL (starting with `https://` or `http://`) of the original asset to resize. -For example, this URL will source an HD video from an R2 bucket, shorten it, crop -and resize it as a square, and remove the audio. +For example, this URL will source an HD video from an R2 bucket, shorten it, crop and resize it as a square, and remove the audio. ``` https://example.com/media/mode=video,time=5s,duration=5s,width=500,height=500,fit=crop,audio=false/https://pub-8613b7f94d6146408add8fefb52c52e8.r2.dev/aus-mobile-demo.mp4 @@ -59,98 +44,88 @@ https://example.com/media/mode=video,time=5s,duration=5s,width=500,height=500,fi The result is an MP4 that can be used in an HTML video element without a player library. -### Options +## Options -#### `mode` +### `mode` -Specify the kind of output to generate. +Specifies the kind of output to generate. -- `video` — output an (H.264/AAC) optimized MP4 file -- `frame` — output a still image -- `spritesheet` — output a JPEG with multiple frames +- `video`: Outputs an H.264/AAC optimized MP4 file. +- `frame`: Outputs a still image. +- `spritesheet`: Outputs a JPEG with multiple frames. -#### `time` +### `time` -When, in the input file, to start extracting the output. Depends on `mode`: +Specifies when to start extracting the output in the input file. Depends on `mode`: -- When `mode` is `spritesheet` or `video`, the timestamp where the output will start -- When `mode` is `frame`, the timestamp from which to extract the still image -- Format as a time string, for example: 5s, 2m +- When `mode` is `spritesheet` or `video`, specifies the timestamp where the output will start. +- When `mode` is `frame`, specifies the timestamp from which to extract the still image. +- Formats as a time string, for example: 5s, 2m - Acceptable range: 0 – 30s - Default: 0 -#### `duration` +### `duration` The duration of the output video or spritesheet. Depends on `mode`: -- When `mode` is `video`, the duration of the output. -- When `mode` is `spritesheet`, the time range from which to select frames. +- When `mode` is `video`, specifies the duration of the output. +- When `mode` is `spritesheet`, specifies the time range from which to select frames. -#### `fit` +### `fit` -In combination with `width` and `height`, how to resize and crop the output. In -the event the output is resized, it will always resize proportionally so content -is not stretched. +In combination with `width` and `height`, specifies how to resize and crop the output. If the output is resized, it will always resize proportionally so content is not stretched. -- `contain` — Respecting aspect ratio, scale a video up or down to be entirely - contained within output dimensions. -- `scale-down` — Same as contain, but downscale to fit only. Do not upscale. -- `cover` — Respecting aspect ratio, scale a video up or down to entirely cover - the output dimensions, with a center-weighted crop of the remainder. +- `contain`: Respecting aspect ratio, scales a video up or down to be entirely contained within output dimensions. +- `scale-down`: Same as contain, but downscales to fit only. Do not upscale. +- `cover`: Respecting aspect ratio, scales a video up or down to entirely cover the output dimensions, with a center-weighted crop of the remainder. -#### `height` +### `height` Specifies maximum height of the output in pixels. Exact behavior depends on `fit`. -- Acceptable range: 10 - 2000 pixels +- Acceptable range: 10-2000 pixels -#### `width` +### `width` -Specifies maximum width of the image in pixels. Exact behavior depends on `fit`. +Specifies the maximum width of the image in pixels. Exact behavior depends on `fit`. -- Acceptable range: 10 - 2000 pixels +- Acceptable range: 10-2000 pixels -#### `audio` +### `audio` -When `mode` is `video`, specifies whether or not to include the source audio in -the output. +When `mode` is `video`, specifies whether or not to include the source audio in the output. -- true — include source audio -- false — output will be silent -- Default: true +- `true`: Includes source audio. +- `false`: Output will be silent. +- Default: `true` -#### `format` +### `format` -If `mode` is `frame`, specifies image output format. +If `mode` is `frame`, specifies the image output format. -- Acceptable options: jpg, png +- Acceptable options: `jpg`, `png` -### Source video requirements +## Source video requirements -Input video must be less than 40MB. Please contact Stream if this input -limitation is not acceptable. +Input video must be less than 40MB. Contact Stream if the input limitation is unacceptable. -Input video should be an MP4 with H.264 encoded video and AAC or MP3 encoded -audio. Other formats may work but are untested. +Input video should be an MP4 with H.264 encoded video and AAC or MP3 encoded audio. Other formats may work but are untested. ## Limitations -Media Transformations is currently in beta. During this period: +Media Transformations are currently in beta. During this period: - Transformations are available for all enabled zones free-of-charge. -- Restricting allowed origins for transformations is coming soon. -- Outputs from Media Transformations will be cached, but in the event they must - be regenerated, the origin fetch is not cached and may result in subsequent - requests to the origin asset. +- Restricting allowed origins for transformations are coming soon. +- Outputs from Media Transformations will be cached, but if they must be regenerated, the origin fetch is not cached and may result in subsequent requests to the origin asset. ## Pricing Media Transformations will be free for all customers while in beta. -After that, Media Transforamtions and Image Transformations will use the same -subscriptions and usage metrics. Generating a still frame (single image) from a -video counts as 1 transformation. Generating an optimized video counts as 1 -transformation _per second of the output_ video. Each unique transformation is -only billed once per month. All Media and Image Transformations cost $0.50 per -1,000 monthly unique transformation operations, with a free monthly allocation -of 5,000. +After that, Media Transforamtions and Image Transformations will use the same subscriptions and usage metrics. + +- Generating a still frame (single image) from a video counts as 1 transformation. +- Generating an optimized video counts as 1 transformation _per second of the output_ video. +- Each unique transformation is only billed once per month. +- All Media and Image Transformations cost $0.50 per 1,000 monthly unique transformation operations, with a free monthly allocation of 5,000.