Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore(http): Move Ogg guide, HTTP method fixes #37026

Merged
merged 7 commits into from
Dec 1, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion files/en-us/_redirects.txt
Original file line number Diff line number Diff line change
Expand Up @@ -1110,7 +1110,7 @@
/en-US/docs/Common_CSS_Questions /en-US/docs/Learn/CSS/Howto/CSS_FAQ
/en-US/docs/Common_XSLT_Errors /en-US/docs/Web/XSLT/Common_errors
/en-US/docs/Configuring_Build_Options https://firefox-source-docs.mozilla.org/setup/configuring_build_options.html
/en-US/docs/Configuring_servers_for_Ogg_media /en-US/docs/Web/HTTP/Configuring_servers_for_Ogg_media
/en-US/docs/Configuring_servers_for_Ogg_media /en-US/docs/Web/Media/Formats/Configuring_servers_for_Ogg_media
/en-US/docs/Consistent_List_Indentation /en-US/docs/Web/CSS/CSS_lists/Consistent_list_indentation
/en-US/docs/Const_statement /en-US/docs/Web/JavaScript/Reference/Statements/const
/en-US/docs/Content_negotiation /en-US/docs/Web/HTTP/Content_negotiation
Expand Down Expand Up @@ -12281,6 +12281,7 @@
/en-US/docs/Web/HTTP/Basics_of_HTTP/Resource_URLs /en-US/docs/Web/URI/Schemes/resource
/en-US/docs/Web/HTTP/CORS/Errors/Reason:_CORS_header_‘Origin’_cannot_be_added /en-US/docs/Web/HTTP/CORS/Errors/CORSOriginHeaderNotAdded
/en-US/docs/Web/HTTP/Caching_FAQ /en-US/docs/Web/HTTP/Caching
/en-US/docs/Web/HTTP/Configuring_servers_for_Ogg_media /en-US/docs/Web/Media/Formats/Configuring_servers_for_Ogg_media
/en-US/docs/Web/HTTP/Controlling_DNS_prefetching /en-US/docs/Web/HTTP/Headers/X-DNS-Prefetch-Control
/en-US/docs/Web/HTTP/Cookies/Cookie_Prefixes /en-US/docs/Web/HTTP/Cookies#Cookie_prefixes
/en-US/docs/Web/HTTP/Cross-Origin_Resource_Policy_(CORP) /en-US/docs/Web/HTTP/Cross-Origin_Resource_Policy
Expand Down
36 changes: 18 additions & 18 deletions files/en-us/_wikihistory.json
Original file line number Diff line number Diff line change
Expand Up @@ -98759,24 +98759,6 @@
"teoli"
]
},
"Web/HTTP/Configuring_servers_for_Ogg_media": {
"modified": "2019-09-10T19:10:12.290Z",
"contributors": [
"Sheppy",
"fscholz",
"bholley",
"chrisdavidmills",
"teoli",
"kscarfone",
"Dikrib",
"Sephr",
"BenB",
"cpearce",
"Zcorpan",
"Varmaa",
"sorinelpusti"
]
},
"Web/HTTP/Connection_management_in_HTTP_1.x": {
"modified": "2019-11-27T11:05:48.174Z",
"contributors": [
Expand Down Expand Up @@ -122592,6 +122574,24 @@
"modified": "2020-06-01T18:13:20.323Z",
"contributors": ["atd30", "Sheppy"]
},
"Web/Media/Formats/Configuring_servers_for_Ogg_media": {
"modified": "2019-09-10T19:10:12.290Z",
"contributors": [
"Sheppy",
"fscholz",
"bholley",
"chrisdavidmills",
"teoli",
"kscarfone",
"Dikrib",
"Sephr",
"BenB",
"cpearce",
"Zcorpan",
"Varmaa",
"sorinelpusti"
]
},
"Web/Media/Formats/Containers": {
"modified": "2020-04-18T23:02:19.945Z",
"contributors": ["sideshowbarker", "FFV47", "Sheppy", "mukhtar-github"]
Expand Down
2 changes: 1 addition & 1 deletion files/en-us/web/html/element/video/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -540,4 +540,4 @@ Some media file types let you provide more specific information using the [`code
- {{htmlelement("audio")}}
- [Using HTML audio and video](/en-US/docs/Learn/HTML/Multimedia_and_embedding/Video_and_audio_content)
- [Manipulating video using canvas](/en-US/docs/Web/API/Canvas_API/Manipulating_video_using_canvas)
- [Configuring servers for Ogg media](/en-US/docs/Web/HTTP/Configuring_servers_for_Ogg_media)
- [Configuring servers for Ogg media](/en-US/docs/Web/Media/Formats/Configuring_servers_for_Ogg_media)
2 changes: 1 addition & 1 deletion files/en-us/web/http/cookies/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ Set-Cookie: tasty_cookie=strawberry
```

> [!NOTE]
> Find out how to use the `Set-Cookie` header in various server-side languages/frameworks: [PHP](https://www.php.net/manual/en/function.setcookie.php), [Node.js](https://nodejs.org/dist/latest-v14.x/docs/api/http.html#http_response_setheader_name_value), [Python](https://docs.python.org/3/library/http.cookies.html), [Ruby on Rails](https://api.rubyonrails.org/classes/ActionDispatch/Cookies.html).
> Find out how to use the `Set-Cookie` header in various server-side languages/frameworks: [PHP](https://www.php.net/manual/en/function.setcookie.php), [Node.js](https://nodejs.org/docs/latest-v19.x/api/http.html#responsesetheadername-value), [Python](https://docs.python.org/3/library/http.cookies.html), [Ruby on Rails](https://api.rubyonrails.org/classes/ActionDispatch/Cookies.html).

When a new request is made, the browser usually sends previously stored cookies for the current domain back to the server within a {{HTTPHeader("Cookie")}} HTTP header:

Expand Down
2 changes: 1 addition & 1 deletion files/en-us/web/http/csp/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -581,7 +581,7 @@ The server handling these requests can then store or process the incoming report

## See also

- [Mitigate cross-site scripting with a strict Content Security Policy](https://web.dev/strict-csp) on web.dev (2024)
- [Mitigate cross-site scripting with a strict Content Security Policy](https://web.dev/articles/strict-csp) on web.dev (2024)
- [Content Security Policy: A successful mess between hardening and mitigation](https://infocondb.org/con/locomocosec/locomocosec-2019/content-security-policy-a-successful-mess-between-hardening-and-mitigation)
- [Content Security Policy Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Content_Security_Policy_Cheat_Sheet.html) on owasp.org
- [CSP Evaluator](https://csp-evaluator.withgoogle.com/)
2 changes: 1 addition & 1 deletion files/en-us/web/http/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,7 @@ Beginners are encouraged to start with the foundational guides before exploring
- [Browser detection using the user agent](/en-US/docs/Web/HTTP/Browser_detection_using_the_user_agent)
- : It's very rarely a good idea to use user agent sniffing to detect a browser, but there are edge cases that require it.
This document will guide you in doing this as correctly as possible when this is necessary, with an emphasis on considerations to make before embarking on this route.
- [Configuring servers for Ogg media](/en-US/docs/Web/HTTP/Configuring_servers_for_Ogg_media)
- [Configuring servers for Ogg media](/en-US/docs/Web/Media/Formats/Configuring_servers_for_Ogg_media)
- : This guide covers a few server configuration changes that may be necessary for your web server to correctly serve Ogg media files.
This information may also be useful if you encounter other media types your server isn't already configured to recognize.

Expand Down
5 changes: 3 additions & 2 deletions files/en-us/web/http/methods/delete/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
title: DELETE
slug: Web/HTTP/Methods/DELETE
page-type: http-method
browser-compat: http.methods.DELETE
spec-urls: https://www.rfc-editor.org/rfc/rfc9110.html#name-delete
---

{{HTTPSidebar}}
Expand Down Expand Up @@ -111,7 +111,8 @@ Content-Length: 1234

## Browser compatibility

{{Compat}}
The browser doesn't use the `DELETE` method for user-initiated actions, so "browser compatibility" doesn't apply.
Copy link
Collaborator

@hamishwillee hamishwillee Dec 1, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@bsmth All of these method updates "seem reasonable" - meaning I can't think of a case where a browser emits them except via a direct user API call to fetch or XHR or whatever. Nor where the response to a DELETE (or the others) is specially handled as a result of the original DELETE call. So in other words the browser doesn't really have any "DELTEE" implementation as such.

But I wouldn't have changed these without first working to get agreement and removal in BCD. Maybe you already did that? If not, can you kick it off?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But I wouldn't have changed these without first working to get agreement and removal in BCD. Maybe you already did that? If not, can you kick it off?

Earlier in the year we discussed HTTP statuses and headers in BCD where support means "nothing breaks" -> the browser doesn't set them in requests and doesn't act on them in responses, but application-specific logic can be done using fetch(). I'll add this to the BCD call notes for this week to make sure this prose is okay, so thanks for flagging it 👍🏻

Developers can set this request method using [`fetch()`](/en-US/docs/Web/API/Window/fetch).

## See also

Expand Down
5 changes: 5 additions & 0 deletions files/en-us/web/http/methods/patch/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -117,6 +117,11 @@ ETag: "e0023aa4f"

{{Specifications}}

## Browser compatibility

The browser doesn't use the `PATCH` method for user-initiated actions, so "browser compatibility" doesn't apply.
Developers can set this request method using [`fetch()`](/en-US/docs/Web/API/Window/fetch).

## See also

- [HTTP request methods](/en-US/docs/Web/HTTP/Methods)
Expand Down
3 changes: 2 additions & 1 deletion files/en-us/web/http/methods/put/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -90,7 +90,8 @@ Content-Location: /existing.html

## Browser compatibility

{{Compat}}
The browser doesn't use the `PUT` method for user-initiated actions, so "browser compatibility" doesn't apply.
Developers can set this request method using [`fetch()`](/en-US/docs/Web/API/Window/fetch).

## See also

Expand Down
5 changes: 5 additions & 0 deletions files/en-us/web/http/methods/trace/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -96,6 +96,11 @@ Accept: */*

{{Specifications}}

## Browser compatibility

The browser doesn't use the `TRACE` method for user-initiated actions, so "browser compatibility" doesn't apply.
Developers can set this request method using [`fetch()`](/en-US/docs/Web/API/Window/fetch).

## See also

- [HTTP request methods](/en-US/docs/Web/HTTP/Methods)
Expand Down
Original file line number Diff line number Diff line change
@@ -1,42 +1,44 @@
---
title: Configuring servers for Ogg media
slug: Web/HTTP/Configuring_servers_for_Ogg_media
slug: Web/Media/Formats/Configuring_servers_for_Ogg_media
page-type: guide
---

{{HTTPSidebar}}
{{QuickLinksWithSubpages("/en-US/docs/Web/Media")}}

HTML {{HTMLElement("audio")}} and {{HTMLElement("video")}} elements allow media presentation without the need for the user to install any plug-ins or other software to do so.
This guide covers a few server configuration changes that may be necessary for your web server to correctly serve Ogg media files.
HTML {{HTMLElement("audio")}} and {{HTMLElement("video")}} elements allow media presentation without the need for the user to install extensions or other software.
This guide covers server configuration that may be necessary to correctly serve Ogg media files.
This information may also be useful if you encounter other media types your server isn't already configured to recognize.

## Serve media with the correct MIME type

`*.ogg` and `*.ogv` files containing video (possibly with an audio track as well, of course), should be served with the `video/ogg` MIME type. `*.oga` and `*.ogg` files containing only audio should be served with the `audio/ogg` MIME type.

If you don't know whether the Ogg file contains audio or video, you can serve it with the MIME type `application/ogg`, and the browser will treat it as a video file.

Most servers don't by default serve Ogg media with the correct MIME types, so you'll likely need to add the appropriate configuration for this.
- `*.ogg` and `*.ogv` files containing video (possibly with an audio track as well, of course), should be served with the `video/ogg` MIME type.
- `*.oga` and `*.ogg` files containing only audio should be served with the `audio/ogg` MIME type.

Most servers don't serve Ogg media with the correct MIME types by default, so you'll likely need to add the appropriate configuration for this.

For Apache, you can add the following to your configuration:

```plain
```apacheconf
AddType audio/ogg .oga
AddType video/ogg .ogv
AddType application/ogg .ogg
```

You can find specific information about possible media file types and the codecs used within them in our comprehensive [guide to media types and formats on the web](/en-US/docs/Web/Media/Formats). In particular, the article on [media container formats](/en-US/docs/Web/Media/Formats/Containers) will be especially helpful when configuring servers to host media properly.
The article on [media container formats](/en-US/docs/Web/Media/Formats/Containers) is especially helpful when configuring servers to host media properly.

## Handle HTTP 1.1 byte range requests correctly
## Handle range requests correctly

In order to support seeking and playing back regions of the media that aren't yet downloaded, Firefox uses HTTP 1.1 byte-range requests to retrieve the media from the seek target position.
In order to support seeking and playing back regions of the media that aren't yet downloaded, you can uses [range requests](/en-US/docs/Web/HTTP/Range_requests) to retrieve the media from the seek target position.
In addition, it uses byte-range requests to seek to the end of the media (assuming you serve the {{HTTPHeader("Content-Length")}} header) in order to determine the duration of the media.

Your server should accept the {{HTTPHeader("Accept-Ranges")}}`: bytes` HTTP header if it can accept byte-range requests. It must return {{HTTPStatus("206")}}`: Partial content` to all byte range requests; otherwise, browsers can't be sure you actually support byte range requests.
Your server should accept the {{HTTPHeader("Accept-Ranges")}} header if it can accept range requests.
It must return {{HTTPStatus("206", "206 Partial Content")}} to all range requests, otherwise browsers can't determine if the server supports range requests.
Your server must also return `206: Partial Content` for the request `Range: bytes=0-` as well.

For more information, see [HTTP range requests](/en-US/docs/Web/HTTP/Range_requests).
See [range requests](/en-US/docs/Web/HTTP/Range_requests) for more information.

## Include regular key frames

Expand All @@ -49,44 +51,24 @@ By default, [`ffmpeg2theora`](https://gitlab.xiph.org/xiph/ffmpeg2theora) uses o

## Consider using the preload attribute

The HTML {{HTMLElement("audio")}} and {{HTMLElement("video")}} elements provide the `preload` attribute, which tells the browser to attempt to download the entire media when the page loads. Without `preload`, the browser only downloads enough of the media to display the first video frame, and to determine the media's duration.

`preload` is off by default, so if getting to video is the point of your web page, your users may appreciate it if you include `preload` in your video elements. Using `preload="metadata"` will preload the media file's metadata and possibly the first few frames of video. Setting `payload` to `auto` tells the browser to automatically begin downloading the media as soon as the page is loaded, under the assumption that the user will play it.

## Configuration for older Firefox versions

### Serve X-Content-Duration headers

> [!NOTE]
> As of [Firefox 41](/en-US/docs/Mozilla/Firefox/Releases/41), the `X-Content-Duration` header is no longer supported. See [Firefox bug 1160695](https://bugzil.la/1160695) for more details.

The Ogg format doesn't encapsulate the duration of media, so for the progress bar on the video controls to display the duration of the video, Gecko needs to determine the length of the media using other means.

There are two ways Gecko can do this. The best way is to offer an `X-Content-Duration` header when serving Ogg media files. This header provides the duration of the video in seconds (**not** in HH:MM:SS format) as a floating-point value.

For example, if the video is 1 minute and 32.6 seconds long, this header would be:

```http
X-Content-Duration: 92.6
```

If your server provides the `X-Content-Duration` header when serving Ogg media, Gecko doesn't have to do any extra HTTP requests to seek to the end of the file to calculate its duration. This makes the entire process much more efficient as well as more accurate.
The HTML {{HTMLElement("audio")}} and {{HTMLElement("video")}} elements provide the `preload` attribute, which tells the browser to attempt to download the entire media when the page loads. Without `preload`, the browser downloads enough of the media to display the first video frame, and to determine the media's duration.

As an inferior alternative, Gecko can estimate the video length based on the Content-Length. See next point.
- `preload` is off by default, so if getting to video is the point of your web page, your users may appreciate it if you include `preload` in your video elements.
- Using `preload="metadata"` will preload the media file's metadata and possibly the first few frames of video. Setting `payload` to `auto` tells the browser to automatically begin downloading the media as soon as the page is loaded, under the assumption that the user will play it.

### Don't use HTTP compression for media files
## Don't use HTTP compression for Ogg media

One common way to reduce the load on a web server is to use [gzip or deflate compression](https://betterexplained.com/articles/how-to-optimize-your-site-with-gzip-compression/) when serving to a supporting web browser.

Although it's unlikely, it's possible the browser may advertise that it supports HTTP compression (gzip/deflate) using the `Accept-Encoding: gzip,deflate` header when requesting media files. Your server should be configured to not do so. The data in media files is already compressed, so you won't get any real benefit from compression, and the use of compression makes it impossible for the browser to properly seek the video or determine its duration.

Another problem with allowing HTTP compression for media streaming: Apache servers don't send the {{HTTPHeader("Content-Length")}} response header if gzip encoding is used.

### Getting the duration of Ogg media
## Getting the duration of Ogg media

You can use the `oggz-info` tool to get the media duration; this tool is included with the [`oggz-tools`](https://www.xiph.org/oggz/) package. The output from `oggz-info` looks like this:

```plain
```bash
$ oggz-info /g/media/bruce_vs_ironman.ogv
Content-Duration: 00:01:00.046

Expand All @@ -107,12 +89,13 @@ Vorbis: serialno 0708996688
Audio-Channels: 2
```

Note that you can't serve up the reported Content-Duration line reported by `oggz-info`, because it's reported in HH:MM:SS format. You'll need to convert it to seconds only, then serve that as your `X-Content-Duration` value. Just parse out the HH, MM, and SS into numbers, then do (HH\*3600)+(MM\*60)+SS to get the value you should report.
Note that you can't serve up the reported Content-Duration line reported by `oggz-info`, because it's reported in `HH:MM:SS` format.
You'll need to convert it to seconds, then serve that as your `X-Content-Duration` value.
You can do this by parsing the `HH`, `MM`, and `SS` segments, then convert to `(HH * 3600) + (MM * 60) + SS` as the value you should report.

It's important to note that it appears that `oggz-info` makes a read pass of the media in order to calculate its duration, so it's a good idea to store the duration value in order to avoid lengthy delays while the value is calculated for every HTTP request of your Ogg media.

## See also

- [Guide to media types and formats on the web](/en-US/docs/Web/Media/Formats)
- [Video and audio content](/en-US/docs/Learn/HTML/Multimedia_and_embedding/Video_and_audio_content)
- [Codecs in common media types](/en-US/docs/Web/Media/Formats/codecs_parameter)