Skip to content

Commit

Permalink
Merge pull request #1241 from canalplus/feat/track-info-on-media-error
Browse files Browse the repository at this point in the history
Add `trackInfo` property to some `MediaError`
  • Loading branch information
peaBerberian committed May 17, 2023
2 parents 88953e3 + 635236b commit 7cd98dd
Show file tree
Hide file tree
Showing 36 changed files with 1,074 additions and 353 deletions.
1 change: 0 additions & 1 deletion demo/full/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,6 @@
<link rel="stylesheet" href="styles/style.css" media="screen">
<link rel="icon" type="image/x-icon" href="plus.ico" />
<script type="text/javascript" src="./bundle.js" charset="utf-8"></script>
<script async defer src="https://buttons.github.io/buttons.js"></script>
<title>RxPlayer - CANAL+</title>
</head>
<body>
Expand Down
61 changes: 61 additions & 0 deletions demo/full/scripts/components/GitHubButton.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
import * as React from "react";
import { render } from "github-buttons";

const {
useEffect,
useRef,
} = React;

const GitHubButton = ({
href,
ariaLabel,
dataColorScheme = "dark_high_contrast",
dataIcon,
dataShowCount,
dataSize = "large",
dataText,
title,
children,
}: {
href: string;
ariaLabel?: string;
dataColorScheme?: string;
dataIcon?: string;
dataShowCount?: boolean | string;
dataSize?: string;
dataText?: string;
title?: string;
children?: React.ReactNode;
}): JSX.Element => {
const aRef = useRef<HTMLAnchorElement>(null);

useEffect(() => {
const aElement = aRef.current;
if (aElement !== null) {
render(
aElement,
newA => aElement?.parentNode?.replaceChild(newA, aElement),
);
}
});

return (
<span className="button-gh">
<a
ref={aRef}
href={href}
aria-label={ariaLabel}
data-icon={dataIcon}
data-color-scheme={dataColorScheme}
data-show-count={dataShowCount}
data-size={dataSize}
data-text={dataText}
title={title}
>
{children}
</a>
</span>
);
};

export default GitHubButton;
26 changes: 12 additions & 14 deletions demo/full/scripts/controllers/Main.tsx
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
import RxPlayer from "../../../../src/minimal";
import * as React from "react";
import GitHubButton from "../components/GitHubButton";
import Player from "./Player";

function MainComponent(): JSX.Element {
Expand All @@ -20,22 +21,19 @@ function MainComponent(): JSX.Element {
<a aria-label="Go to Canal+ website" href="https://canalplus.com">
<img className="title-logo" alt="CANAL+" src="./assets/canalp.svg"/>
</a>
<span className="button-gh"><a
className="github-button"
<GitHubButton
href="https://github.com/canalplus/rx-player"
data-size="large"
data-icon="octicon-star"
data-show-count="true"
aria-label="Star the RxPlayer on GitHub">
Star
</a></span>
<span className="button-gh"><a
className="github-button"
ariaLabel="Star the RxPlayer on GitHub"
dataIcon="octicon-star"
dataShowCount="true"
dataText="Star"
/>
<GitHubButton
href="https://github.com/canalplus/rx-player/fork"
data-size="large"
aria-label="Fork the RxPlayer on GitHub">
Fork
</a></span>
ariaLabel="Fork the RxPlayer on GitHub"
dataIcon="octicon-repo-forked"
dataText="Fork"
/>
</div>
</div>
<Player />
Expand Down
2 changes: 1 addition & 1 deletion demo/full/styles/style.css
Original file line number Diff line number Diff line change
Expand Up @@ -1062,7 +1062,7 @@ input:checked + .slider:before {

.header-links-buttons {
display: flex;
align-items: baseline;
align-items: center;
}

.header-links-buttons > * {
Expand Down
193 changes: 186 additions & 7 deletions doc/api/Player_Errors.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ all have a `type` property equal to `"NETWORK_ERROR"`.

#### codes

A NetworkError can only have the following code (`code` property):
An error of `type` `NETWORK_ERROR` can only have the following code (`code` property):

- `"PIPELINE_LOAD_ERROR"`: the
[Manifest](../Getting_Started/Glossary.md#manifest) or
Expand Down Expand Up @@ -107,16 +107,30 @@ parsing) or from the browser itself (content playback).

They all have a `type` property equal to `"MEDIA_ERROR"`.

Depending on its `code` property (listed below), a `MEDIA_ERROR` may also have
a supplementary `trackInfo` property, describing the track related to the issue.
The format of that property is decribed in the chapter below listed codes, and
the codes for which it is set are indicated in the corresponding code's
description below.

#### codes

A MediaError can have the following codes (`code` property):
An error of `type` `MEDIA_ERROR` can have the following codes (`code` property):

- `"BUFFER_APPEND_ERROR"`: A media segment could not have been added to the
corresponding media buffer. This often happens with malformed segments.

For those errors, you may be able to know the characteristics of the track
linked to that segment by inspecting the error's `trackInfo` property,
described below.

- `"BUFFER_FULL_ERROR"`: The needed segment could not have been added
because the corresponding media buffer was full.

For those errors, you may be able to know the characteristics of the track
linked to that segment by inspecting the error's `trackInfo` property,
described below.

- `"BUFFER_TYPE_UNKNOWN"`: The type of buffer considered (e.g. "audio" /
"video" / "text") has no media buffer implementation in your build.

Expand All @@ -125,6 +139,9 @@ A MediaError can have the following codes (`code` property):
[Representations](../Getting_Started/Glossary.md#representation) (read quality) in a supported
codec.

For those errors, you may be able to know the characteristics of the track
linked to that codec by inspecting the error's `trackInfo` property, described below.

- `"MANIFEST_PARSE_ERROR"`: Generic error to signal than the
[Manifest](../Getting_Started/Glossary.md#structure_of_a_manifest_object) could not be parsed.

Expand Down Expand Up @@ -193,10 +210,14 @@ A MediaError can have the following codes (`code` property):
This is rarely a problem and may be encountered at a very start of a content
when the initial segment's start is much later than expected.

- `"NO_PLAYABLE_REPRESENTATION"`: The currently chosen Adaptation does not
- `"NO_PLAYABLE_REPRESENTATION"`: One of the currently chosen track does not
contain any playable Representation. This usually happens when every
Representation has been blacklisted due to encryption limitations.

For those errors, you may be able to know the characteristics of the
corresponding track by inspecting the error's `trackInfo` property, described
below.

- `"MANIFEST_UPDATE_ERROR"`: This error should never be emitted as it is
handled internally by the RxPlayer. Please open an issue if you encounter
it.
Expand All @@ -211,16 +232,174 @@ A MediaError can have the following codes (`code` property):
It is triggered when a time we initially thought to be in the bounds of the
Manifest actually does not link to any "Period" of the Manifest.

#### `trackInfo` property

As described in the corresponding code's documentation, A aupplementary
`trackInfo` property may be set on `MEDIA_ERROR` depending on its `code`
property.

That `trackInfo` describes, when it makes sense, the characteristics of the track
linked to an error. For example, you may want to know which video track led to a
`BUFFER_APPEND_ERROR` and thus might be linked to corrupted segments.

The `trackInfo` property has itself two sub-properties:

- `type`: The type of track: `"audio"` for an audio track, `"text"` for a text
track, or `"video"` for a video track.

- `track`: Characteristics of the track. Its format depends on the
`trackInfo`'s `type` property and is described below.

##### For video tracks

When `trackInfo.type` is set to `"video"`, `track` describes a video track. It
contains the following properties:

- `id` (`string`): The id used to identify this track. No other
video track for the same [Period](../Getting_Started/Glossary.md#period)
will have the same `id`.

- `label` (`string|undefined`): A human readable label that may be displayed in
the user interface providing a choice between video tracks.

This information is usually set only if the current Manifest contains one.

- `representations` (`Array.<Object>`):
[Representations](../Getting_Started/Glossary.md#representation) of this
video track, with attributes:

- `id` (`string`): The id used to identify this Representation.
No other Representation from this track will have the same `id`.

- `bitrate` (`Number`): The bitrate of this Representation, in bits per
seconds.

- `width` (`Number|undefined`): The width of video, in pixels.

- `height` (`Number|undefined`): The height of video, in pixels.

- `codec` (`string|undefined`): The video codec the Representation is
in, as announced in the corresponding Manifest.

- `frameRate` (`string|undefined`): The video frame rate.

- `hdrInfo` (`Object|undefined`) Information about the hdr
characteristics of the track.
(see [HDR support documentation](./Miscellaneous/hdr.md#hdrinfo))

- `signInterpreted` (`Boolean|undefined`): If set to `true`, this track is
known to contain an interpretation in sign language.
If set to `false`, the track is known to not contain that type of content.
If not set or set to undefined we don't know whether that video track
contains an interpretation in sign language.

- `isTrickModeTrack` (`Boolean|undefined`): If set to `true`, this track
is a trick mode track. This type of tracks proposes video content that is
often encoded with a very low framerate with the purpose to be played more
efficiently at a much higher speed.

- `trickModeTracks` (`Array.<Object> | undefined`): Trick mode video tracks
attached to this video track.

Each of those objects contain the same properties that a regular video track
(same properties than what is documented here).

It this property is either `undefined` or not set, then this track has no
linked trickmode video track.

##### For audio tracks

When `trackInfo.type` is set to `"audio"`, `track` describes an audio track. It
contains the following properties:

- `id` (`Number|string`): The id used to identify this track. No other
audio track for the same [Period](../Getting_Started/Glossary.md#period)
will have the same `id`.

- `language` (`string`): The language the audio track is in, as set in the
[Manifest](../Getting_Started/Glossary.md#manifest).

- `normalized` (`string`): An attempt to translate the `language`
property into an ISO 639-3 language code (for now only support translations
from ISO 639-1 and ISO 639-3 language codes). If the translation attempt
fails (no corresponding ISO 639-3 language code is found), it will equal the
value of `language`

- `audioDescription` (`Boolean`): Whether the track is an audio
description of what is happening at the screen.

- `dub` (`Boolean|undefined`): If set to `true`, this audio track is a
"dub", meaning it was recorded in another language than the original.
If set to `false`, we know that this audio track is in an original language.
This property is `undefined` if we do not known whether it is in an original
language.

- `label` (`string|undefined`): A human readable label that may be displayed in
the user interface providing a choice between audio tracks.

This information is usually set only if the current Manifest contains one.

- `representations` (`Array.<Object>`):
[Representations](../Getting_Started/Glossary.md#representation) of this video track, with
attributes:

- `id` (`string`): The id used to identify this Representation.
No other Representation from this track will have the same `id`.

- `bitrate` (`Number`): The bitrate of this Representation, in bits per
seconds.

- `codec` (`string|undefined`): The audio codec the Representation is
in, as announced in the corresponding Manifest.

##### For text tracks

When `trackInfo.type` is set to `"text"`, `track` describes a text track. It
contains the following properties:

- `id` (`string`): The id used to identify this track. No other
text track for the same [Period](../Getting_Started/Glossary.md#period)
will have the same `id`.

- `language` (`string`): The language the text trac./../Basic_Methods/loadVideo.md#transport set in the
[Manifest](../Getting_Started/Glossary.md#manifest).

- `normalized` (`string`): An attempt to translate the `language`
property into an ISO 639-3 language code (for now only support translations
from ISO 639-1 and ISO 639-3 language codes). If the translation attempt
fails (no corresponding ISO./../Basic_Methods/loadVideo.md#transport found), it will equal the
value of `language`

- `label` (`string|undefined`): A human readable label that may be displayed in
the user interface providing a choice between text tracks.

This information is usually set only if the current Manifest contains one.

- `closedCaption` (`Boolean`): Whether the track is specially adapted for
the hard of hearing or not.

- `forced` (`Boolean`): If `true` this text track is meant to be displayed by
default if no other text track is selected.

It is often used to clarify dialogue, alternate languages, texted graphics or
location and person identification.


### ENCRYPTED_MEDIA_ERROR

Those errors are linked to the Encrypted Media Extensions. They concern various
DRM-related problems.
Those errors are linked to the "Encrypted Media Extensions" API.
They concern various DRM-related problems.

They all have a `type` property equal to `"ENCRYPTED_MEDIA_ERROR"`.

When its code is set to `KEY_STATUS_CHANGE_ERROR`, an ENCRYPTED_MEDIA_ERROR
generally also have a `keyStatuses` property, which is documented in the
corresponding `KEY_STATUS_CHANGE_ERROR` code explanation below.

#### codes

An EncryptedMediaError can have the following codes (`code` property):
An error of `type` `ENCRYPTED_MEDIA_ERROR` can have the following codes (`code`
property):

- `"INCOMPATIBLE_KEYSYSTEMS"`: None of the provided key systems was
compatible with the current browser.
Expand Down Expand Up @@ -295,7 +474,7 @@ They all have a `type` property equal to `"OTHER_ERROR"`.

#### codes

An OtherError can have the following codes (`code` property):
An error of `type` `OTHER_ERROR` can have the following codes (`code` property):

- `"PIPELINE_LOAD_ERROR"`: The
[Manifest](../Getting_Started/Glossary.md#structure_of_a_manifest_object) or segment
Expand Down
Loading

0 comments on commit 7cd98dd

Please sign in to comment.