Skip to content

Commit ecd9bca

Browse files
dcpenapedrosousahyperlint-ai[bot]
authored
[Stream] Update Upload videos section (#16479)
* Update Upload videos section * Apply suggestions from code review Co-authored-by: Pedro Sousa <[email protected]> Co-authored-by: hyperlint-ai[bot] <154288675+hyperlint-ai[bot]@users.noreply.github.com> * Removed instance of "via" * Fixed casing for tus --------- Co-authored-by: Pedro Sousa <[email protected]> Co-authored-by: hyperlint-ai[bot] <154288675+hyperlint-ai[bot]@users.noreply.github.com>
1 parent 9f7aca2 commit ecd9bca

File tree

6 files changed

+332
-319
lines changed

6 files changed

+332
-319
lines changed

‎src/content/docs/stream/uploading-videos/direct-creator-uploads.mdx‎

Lines changed: 32 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -2,37 +2,34 @@
22
pcx_content_type: example
33
title: Direct creator uploads
44
sidebar:
5-
order: 4
6-
5+
order: 5
76
---
87

9-
Direct creator uploads let your end users to upload videos directly to Cloudflare Stream, without exposing your API token to clients.
8+
Direct creator uploads let your end users upload videos directly to Cloudflare Stream without exposing your API token to clients.
109

11-
**Two options:**
10+
- If your video is a [basic upload](/stream/uploading-videos/direct-creator-uploads/#basic-uploads) under 200 MB and users do not need resumable uploads, generate a URL that accepts an HTTP post request.
1211

13-
1. For videos under 200MB, [generate URLs that accept an HTTP POST request](/stream/uploading-videos/direct-creator-uploads#basic-upload-flow-for-small-videos).
14-
2. For videos over 200 MB, or if you need to allow users to resume uploads that may be interrupted by poor network connections or users closing your app while videos are still uploading, [generate URLs that use the tus protocol](/stream/uploading-videos/direct-creator-uploads#advanced-upload-flow-using-tus-for-large-videos).
12+
- If your video is over 200 MB or if you need to allow users to [resume interrupted uploads](/stream/uploading-videos/direct-creator-uploads/#resumable-uploads), generate a URL using the tus protocol.
1513

16-
## Basic upload flow, for small videos
14+
In either case, you must specify a maximum duration to reserve for the user's upload to ensure it can be accommodated within your available storage.
1715

18-
Use this if your users upload videos under 200MB, and you do not need to allow resumable uploads.
16+
## Basic uploads
1917

20-
### Step 1: Generate a unique one-time upload URL
18+
Use this option if your users upload videos under 200 MB, and you do not need to allow resumable uploads.
2119

22-
[API Reference Docs for `/direct_upload`](/api/operations/stream-videos-upload-videos-via-direct-upload-ur-ls)
20+
1. Generate a unique, one-time upload URL using the [Direct upload API](/api/operations/stream-videos-upload-videos-via-direct-upload-ur-ls).
2321

24-
```bash title="Request"
25-
curl -X POST \
26-
-H 'Authorization: Bearer <API_TOKEN>' \
27-
https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream/direct_upload \
22+
```sh title="Generate upload"
23+
curl https://api.cloudflare.com/client/v4/accounts/{account_id}/stream/direct_upload \
24+
--header 'Authorization: Bearer <API_TOKEN>' \
2825
--data '{
2926
"maxDurationSeconds": 3600
3027
}'
3128
```
3229

3330
{/* <!-- videodelivery.net is correct domain. See STREAM-4364 --> */}
3431

35-
```json title="Response"
32+
```json output {3}
3633
{
3734
"result": {
3835
"uploadURL": "https://upload.videodelivery.net/f65014bc6ff5419ea86e7972a047ba22",
@@ -44,30 +41,26 @@ https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream/direct_upload
4441
}
4542
```
4643

47-
## Step 2: Use the upload URL in your app
48-
49-
Using the `uploadURL` provided in the previous request, users can upload video
50-
files. Uploads are limited to 200 MB in size.
44+
2. With the `uploadURL` from the previous step, users can upload video files that are limited to 200 MB in size. Refer to the example request below.
5145

5246
{/* <!-- videodelivery.net is correct domain. See STREAM-4364 --> */}
5347

54-
```bash title="Upload a video file to the unique one-time upload URL"
55-
curl -X POST \
56-
-F file=@/Users/mickie/Downloads/example_video.mp4 \
48+
```bash {3} title="Upload a video to the unique one-time upload URL"
49+
curl --request POST \
50+
--form file=@/Users/mickie/Downloads/example_video.mp4 \
5751
https://upload.videodelivery.net/f65014bc6ff5419ea86e7972a047ba22
5852
```
5953

6054
A successful upload will receive a `200` HTTP status code response. If the upload does not meet
61-
the upload constraints defined at time of creation or is larger than 200 MB in
62-
size, you will receive a `4xx` HTTP status code response.
55+
the upload constraints defined at time of creation or is larger than 200 MB in size, you will receive a `4xx` HTTP status code response.
6356

64-
## Advanced upload flow using tus, for large videos
57+
## Resumable uploads
6558

66-
[tus](https://tus.io/) is a protocol that supports resumable uploads. Use TUS if your users upload videos over 200MB **or** you need to allow resumable uploads. If your users upload via a mobile app or often use your app or website using a mobile network (ex: LTE, 5G), we strongly encourage you to use TUS.
59+
1. Create your own API endpoint that returns an upload URL.
6760

68-
### Step 1: Create your own API endpoint that returns an upload URL
61+
The example below shows how to build a Worker to get a URL you can use to upload your video. The one-time upload URL is returned in the `Location` header of the response, not in the response body.
6962

70-
```javascript title="Example API endpoint that requests a one-time tus upload URL from Cloudflare Stream, and returns it in the location header"
63+
```javascript {23} title="Example API endpoint"
7164
export async function onRequest(context) {
7265
const { request, env } = context;
7366
const { CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_API_TOKEN } = env;
@@ -96,13 +89,9 @@ export async function onRequest(context) {
9689
}
9790
```
9891

99-
Note in the example above that the one-time upload URL is returned in the `Location` header of the response, not in the response body.
100-
101-
### Step 2: Use this API endpoint with your tus client
92+
2. Use this API endpoint **directly** in your tus client. A common mistake is to extract the upload URL from your new API endpoint, and use this directly. See below for a complete example of how to use the API from Step 1 with the uppy tus client.
10293

103-
Use this API endpoint **directly** in your tus client. A common mistake is to extract the upload URL from your new API endpoint, and use this directly. See below for a complete example of how to use the API from Step 1 with the uppy tus client.
104-
105-
```html title="Upload a video, using your API endpoint using the uppy tus client"
94+
```html {35} title="Upload a video using the uppy tus client"
10695
<html>
10796
<head>
10897
<link href="https://releases.transloadit.com/uppy/v3.0.1/uppy.min.css" rel="stylesheet" />
@@ -150,11 +139,11 @@ Use this API endpoint **directly** in your tus client. A common mistake is to ex
150139

151140
For more details on using tus and example client code, refer to [Resumable uploads with tus](/stream/uploading-videos/upload-video-file/#resumable-uploads-with-tus-for-large-files).
152141

153-
### Upload-Metadata header syntax
142+
## Upload-Metadata header syntax
154143

155144
You can apply the [same constraints](/api/operations/stream-videos-upload-videos-via-direct-upload-ur-ls) as Direct Creator Upload via basic upload when using tus. To do so, you must pass the `expiry` and `maxDurationSeconds` as part of the `Upload-Metadata` request header as part of the first request (made by the Worker in the example above.) The `Upload-Metadata` values are ignored from subsequent requests that do the actual file upload.
156145

157-
Upload-Metadata header should contain key-value pairs. The keys are text and the values should be base64. Separate the key and values by a space, *not* an equal sign. To join multiple key-value pairs, include a comma with no additional spaces.
146+
The `Upload-Metadata` header should contain key-value pairs. The keys are text and the values should be encoded in base64. Separate the key and values by a space, *not* an equal sign. To join multiple key-value pairs, include a comma with no additional spaces.
158147

159148
In the example below, the `Upload-Metadata` header is instructing Stream to only accept uploads with max video duration of 10 minutes, uploaded prior to the expiry timestamp, and to make this video private:
160149

@@ -163,18 +152,18 @@ In the example below, the `Upload-Metadata` header is instructing Stream to only
163152
`NjAw` is the base64 encoded value for "600" (or 10 minutes).
164153
`MjAyNC0wMi0yN1QwNzoyMDo1MFo=` is the base64 encoded value for "2024-02-27T07:20:50Z" (an RFC3339 format timestamp)
165154

166-
## Tracking user upload progress
155+
## Track upload progress
167156

168157
After the creation of a unique one-time upload URL, you may wish to retain the unique identifier (`uid`) returned in the response to track the progress of a user's upload.
169158

170159
You can do that two ways:
171160

172-
1. You can [search for a video](/stream/manage-video-library/searching/) with the UID
173-
to understand it's status.
161+
- [Search for a video](/stream/manage-video-library/searching/) with the UID to check the status.
162+
163+
- [Create a webhook subscription](/stream/manage-video-library/using-webhooks/) to receive notifications about the video status. These notifications include the video's UID.
174164

175-
2. You can [create a webhook subscription](/stream/manage-video-library/using-webhooks/) to receive notifications
176-
regarding the status of videos. These notifications include the video's UID.
165+
## Billing considerations
177166

178-
### Billing considerations
167+
Direct Creator Upload links count towards your storage limit even if your users have not yet uploaded video to this URL. If the link expires before it is used or the upload cannot be processed, the storage reservation will be released. Otherwise, once the upload is encoded, its true duration will be counted toward storage and the reservation will be released.
179168

180-
* One-time upload URLs count towards your storage limit, even if your users have not yet uploaded video to this URL. For example, if you generate a one-time upload URL with a `maxDurationSeconds` value of `60`, that expires 30 minutes from now (the default value of `expiry`), until the upload URL expires, this will count as one minute of video stored. This ensures that you do not inadvertently generate upload URLs that fail for your users once you've reached your storage limit. You can add storage to your subscription anytime via the Cloudflare Dashboard, and customize the `expiry` to a duration of your choosing. We recommend setting a short duration and generating this URL on-demand, at the moment when the user needs to upload a video.
169+
For a detailed breakdown of pricing and example scenarios, refer to [Pricing](/stream/pricing/).

‎src/content/docs/stream/uploading-videos/index.mdx‎

Lines changed: 40 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -2,18 +2,49 @@
22
title: Upload videos
33
pcx_content_type: navigation
44
sidebar:
5-
order: 3
6-
5+
order: 1
76
---
87

9-
Stream provides four ways to upload videos to cover a diverse set of use cases.
8+
Before you upload your video, review the options for uploading a video, supported formats, and recommendations.
9+
10+
## Upload options
11+
12+
| Upload method | When to use |
13+
|---------------|-------------|
14+
|[Stream Dashboard](https://dash.cloudflare.com/?to=/:account/stream)| Upload videos from the Stream Dashboard without writing any code.
15+
|[Upload from a URL](/stream/uploading-videos/upload-via-link/)| Upload videos from a URL, such as an S3 bucket or content management system.
16+
|[Upload video file](/stream/uploading-videos/upload-video-file/)| Upload videos stored on a computer.
17+
|[Direct creator uploads](/stream/uploading-videos/direct-creator-uploads/)| Allows end users of your website or app to upload videos directly to Cloudflare Stream.
18+
19+
20+
## Supported video formats
21+
1022

23+
:::note
24+
Files must be less than 30 GB, and content should be encoded and uploaded in the same frame rate it was recorded.
25+
:::
1126

27+
- MP4
28+
- MKV
29+
- MOV
30+
- AVI
31+
- FLV
32+
- MPEG-2 TS
33+
- MPEG-2 PS
34+
- MXF
35+
- LXF
36+
- GXF
37+
- 3GP
38+
- WebM
39+
- MPG
40+
- Quicktime
1241

13-
| Upload method | When to use |
14-
| -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
15-
| [Stream Dashboard](https://dash.cloudflare.com?to=/:account/stream) | Upload videos from the Stream Dashboard, without writing any code. |
16-
| [Copy via link](/stream/uploading-videos/upload-via-link/) | Upload videos from a URL, such as an S3 bucket or content management system. |
17-
| [Direct creator uploads](/stream/uploading-videos/direct-creator-uploads/) | Allow end users of your website or app to upload videos directly to Cloudflare Stream. |
18-
| [Upload video file](/stream/uploading-videos/upload-video-file/) | Upload videos when the video file is stored on a computer. |
42+
## Recommendations for on-demand videos
1943

44+
- Optional but ideal settings:
45+
- MP4 containers
46+
- AAC audio codec
47+
- H264 video codec
48+
- 60 or fewer frames per second
49+
- Closed GOP (_Only required for live streaming._)
50+
- Mono or Stereo audio. Stream will mix audio tracks with more than two channels down to stereo.

0 commit comments

Comments
 (0)