rx-player 3.33.0 → 3.33.1

package/src/parsers/manifest/dash/wasm-parser/README.md

@@ -1,267 +0,0 @@
-# DASH-WASM MPD parser #########################################################
-
-This directory exposes a WebAssembly-based MPD parser, whose intent is to be
-faster than the default JS-based one, especially on very large (multiple
-megabytes) MPDs.
-
-
-
-## What is this ################################################################
-
-### How Manifest parsing works in the RxPlayer #################################
-
-In the RxPlayer every Manifest parser output the same final Manifest format
-which follow the same structure regardless of the transport protocol used (e.g.
-DASH, Smooth etc.).
-
-For the MPD (DASH's Manifest format), this transformation (from an XML to that
-final Manifest format) happens in two steps:
-  1. first from the XML to a JS object very close that representation (same
-     hierarchy, same elements and attributes names).
-
-     This is what we call the "intermediate representation" (kind of a cheeky
-     name, because that expression is usually used for more complex compiler
-     mid-compilation structures, but we found the name to be a fit also in our
-     case).
-
-  2. Then from this "intermediate representation" to the final Manifest.
-
-The idea is that the "intermediate representation" is much easier to manipulate
-than the XML format in JavaScript.
-
-
-
-### Problems with the JavaScript parser ########################################
-
-Before the DASH-WASM parser, we only had the JavaScript parser, which relied on
-the browser's DOM APIs (e.g. `DOMParser`).
-
-This parser works fine but we found that its performance was really poor when
-encoutering huge MPDs (several MBs), that we're dealing with at Canal+ on a
-regular basis.
-Usually those problematic MPDs have several gigantic `<SegmentTimeline>`
-elements that takes a lot of time to parse.
-
-After multiple tests, profiling and improvements, it appeared that the issue had
-to do with XML parsing and the DOM APIs (regarding the speed of the parsing
-operation, but also some stability issues most likely related to garbage
-collection pressure).
-
-Moreover, on some embedded devices, this operation could take several seconds.
-This leaded us to try to implement a parser running in a WebWorker (to avoid
-blocking the main thread, which is also handling the user interface).
-
-As no DOM API are available in a WebWorker, we had to re-define the XML parsing
-APIs.  We first opted for a JavaScript library, yet found performance in our
-initial tests to be subpar.
-We ended up trying with WebAssembly instead.
-
-I chose to start a proof-of-concept in Rust because I already had some
-experience with it. After the first results, which were exceeding our
-expectations, it became clear that this strategy could be the way to go.
-
-Even if initially, this parser was written to run in a WebWorker, this is not
-(yet?) the case. This is because:
-
-  1. we found that the performance of the parser rewrote in WebAssembly to be
-     more than acceptable, even in the main thread
-
-  2. after some initial tests, we noticed that adding a worker into the mix
-     could add some non-negligible time penalties.
-     This could potentially be avoidable but we did not take the time to work on
-     that for now.
-
-  3. we see a lot of improvements which could make running in a main thread less
-     of a problem, most notably parsing at the same time than the MPD request is
-     pending, small MPD chunk by small MPD chunk.
-
-Due to this, we decided to only develop and integrate the WebAssembly part at
-first, which will run in the main thread. We may add WebWorker-related logic in
-future releases.
-
-
-
-### What is WebAssembly ########################################################
-
-WebAssembly is a binary format for executables that can be executed - among
-other platforms - in modern browsers.
-It is generally compiled from code written in other languages (even if a
-WebAssembly text format does exist).
-
-The initial idea was both to provide a possibly-faster language than JavaScript
-in the browser and to allow programs written in other languages than JavaScript
-to run in the browser with few efforts.
-
-In the context of the RxPlayer, we only use it for optimization reasons, when
-we noticed that switching the DASH MPD parser to WebAssembly has a high impact
-in terms of performance when compared to the equivalent JavaScript code.
-
-
-### Where does the DASH-WASM parser fits into this #############################
-
-The DASH-WASM MPD parser only does the first step of transforming the initial
-XML format into the "intermediate representation", by using WebAssembly.
-
-We could resume by writing it this way. The DASH-WASM parser's code only does
-the following things:
-  1. It browses the XML
-  2. It converts each of its attributes to the wanted format (e.g. floats,
-     JS strings, integers, booleans...)
-  3. From those, it constructs the "intermediate representation" of the MPD
-
-After those steps, the rest of the transformation into the final Manifest is
-done by a common code (common with the JS parser) written in JavaScript.
-
-This logic was written as such because:
-
-  - when we profiled the performance of our JS parser, we noticed that the
-    performance issue was overwhelmingly linked to the APIs related to XML
-    parsing
-
-  - as we were introducing another language into the RxPlayer, we wanted its
-    maintenance cost to be as small as possible, thus keeping the not-so
-    problematic steps in JavaScript.
-
-
-
-## How this parser is written ##################################################
-
-### Directories ################################################################
-
-The DASH-WASM parser comes into part:
-
-  - the Rust part, written in the `rs` directory, that browses the XML and
-    convert values to the right format.
-
-  - the TypeScript part, written in the `ts` directory that constructs the
-    "intermediate representation" JS object from what is parsed by the Rust
-    part.
-
-The parser's entry point is also written in TypeScript and can be found in the
-`ts` directory.
-
-
-### How Rust and TypeScript interact ###########################################
-
-#### Architecture
-
-Currently, the DASH-WASM parser parses in one go the XML.
-
-  1. The XML data is continuously fed to the WebAssembly, which just sees it as
-     an array of bytes, it then goes through the quick-xml dependency - a Rust
-     "crate" (equivalent to a node module).
-
-  2. As quick-xml encounters new XML elements (it uses an event-driven SAX
-     parser approach which continuously parses the MPD, not a DOM one reading
-     it fully in advance), quick-xml will notify our WebAssembly code that this
-     is the case.
-
-  3. The WebAssembly code assigns to each recognized element a number (defined
-     as a Rust and TypeScript enum).
-
-     If the XML element encountered is recognized, it will call a JavaScript
-     callback with the right number, to signal that this element has been
-     encountered.
-
-  4. This callback, registered by the TypeScript code, begin to create the
-     object corresponding to that element and update some callbacks called
-     by Rust so that new elements and attributes are considered as part of
-     this element.
-
-  5. The WebAssembly then iterates through each of that element's attribute.
-
-     When it recognizes one for a given element (e.g. Period@start):
-       - it converts it to the right format (integer, float, UTF-8 string).
-       - it assigns a number to this attribute (like for elements, but with a
-         different enum).
-       - it calls a JavaScript callback signaling that that attribute has been
-         encountered with its value (in some cases, a pointer and potential
-         length of the value).
-
-   6. The attribute is received by the TypeScript code. It will generally do a
-      small conversion again to the right type (e.g. UTF-8 to JS String, floats
-      and integers to JS numbers and so on) and then add it to the object
-      created previously for that element.
-
-   7. The WebAssembly code continues to parse elements and attributes inside
-      that signaled element and continue to call the corresponding JavaScript
-      callbacks as it does so.
-
-      Once it encounters a closing element, it checks if the element is
-      recognized (is part of the element enum). If that's the case, it calls
-      another JavaScript callback with that element's number signaling that its
-      closing tag was encountered.
-
-   8. The callback, defined in the TypeScript code, handles the closing tag
-      event mainly by re-updating other callbacks (so new elements and
-      attributes are not considered part of this closed element anymore).
-
-   9. The same logic is continued until the end of the MPD.
-
-There's also another JavaScript callback not introduced here to simplify. This
-is a callback to let the WebAssembly code signal when minor errors have been
-encountered when parsing the MPD (e.g. invalid attributes' data).
-
-This current architecture has initially been designed for simplicity, seeing
-that its results were more than suitable, we stood with it.
-If you think another approach would be preferable for any reason, don't hesitate
-to propose a change (through an issue first)
-
-
-### Details on FFI #############################################################
-
-Technically, some data and function calls needs to cross the language boundaries
-between the compiled JavaScript and WebAssembly code.
-
-On the JavaScript/TypeScript-side, everything stays relatively simple, with few
-considerations to have. TypeScript functions are defined, which take `number`
-arguments, and are communicated when instantiating a new WebAssembly module.
-
-On Rust-side, we exploit multiple FFI features:
-
-  - compiling Rust with the `"cdylib"` `crate-type` (as indicated in the
-    `Cargo.toml` file). This has for effect to create a "system" dynamic
-    library, which will follow the stable C ABI.
-
-  - marking function defined in JavaScript with an `extern "C" {` block, to
-    indicate that they follow the C ABI.
-
-  - marking function defined in Rust but callable in JavaScript both with `pub`
-    and `extern "C"` indicating that they are public function using the C ABI.
-
-    Also those functions have the `#[no_mangle]` attribute, disabling name
-    mangling for these so they can be easily called from JavaScript by using the
-    same name.
-
-  - data other than integers are usually exchanged through a duo of a pointer
-    and a length.
-    JavaScript has access to the full WebAssembly's memory, meaning that large
-    chunk of data can just be exchanged by reading from and writing to this
-    memory with only a pointer and a length given.
-
-
-
-## How to build the Rust code ##################################################
-
-The Rust code is compiled through npm scripts, just like all other building
-logic in the RxPlayer.
-
-To be able to call the corresponding npm script [1], you will need to:
-
-  1. Install [cargo](https://doc.rust-lang.org/cargo/getting-started/installation.html),
-     which is roughly Rust's npm.
-
-  2. Install [binaryen](https://github.com/WebAssembly/binaryen), which is a
-     WebAssembly toolbox we're using to optimize the built wasm file.
-
-If you see error messages while building related to a "wasm32-unknown-unknown"
-target not being installed, you should install it.
-
-If you use `rustup` this can be done for example by writing:
-```sh
-rustup target add wasm32-unknown-unknown
-```
-
-[1] The name of those scripts are not repeated in this document because of the
-fear that they may change in the future, in which case this documentation could
-easily be outdated.

package/src/parsers/manifest/dash/wasm-parser/index.ts

@@ -1,21 +0,0 @@
-/**
- * Copyright 2015 CANAL+ Group
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-import DashWasmParser, {
-  IDashWasmParserOptions,
-} from "./ts/dash-wasm-parser";
-export { IDashWasmParserOptions };
-export default DashWasmParser;

package/src/parsers/manifest/dash/wasm-parser/rs/errors.rs

@@ -1,28 +0,0 @@
-use crate::events::CustomEventType;
-use crate::onCustomEvent;
-
-pub type Result<T> = std::result::Result<T, ParsingError>;
-
-/// Very simple error type, only used to generate a String description of a
-/// parsing error, to then be reported on the JS-side.
-#[derive(Debug, Clone)]
-pub struct ParsingError(pub String);
-
-impl ParsingError {
-    /// Call JS-side callback with this ParsingError in argument to report an
-    /// error.
-    pub fn report_err(&self) {
-        let len = self.0.len();
-        // UNSAFE: We're using FFI, so we don't know how the pointer is used.
-        // Hopefully, the JavaScript-side should clone that value synchronously.
-        unsafe {
-            onCustomEvent(CustomEventType::Error, (*self.0).as_ptr(), len);
-        }
-    }
-}
-
-impl<T: std::error::Error> From<T> for ParsingError {
-    fn from(err: T) -> ParsingError {
-        ParsingError(err.to_string())
-    }
-}

package/src/parsers/manifest/dash/wasm-parser/rs/events.rs

@@ -1,373 +0,0 @@
-use crate::{onTagClose, onTagOpen, ParsingError};
-
-#[derive(Clone, Copy)]
-#[repr(C)]
-pub enum CustomEventType {
-    /// Variant that can be used to log various information on the RxPlayer's
-    /// logger.
-    ///
-    /// Useful for debugging, for example.
-    #[allow(dead_code)]
-    Log = 0,
-
-    /// Variant used to report parsing errors to the RxPlayer.
-    Error = 1,
-}
-
-/// `TagName` enumerates parsed XML elements in an MPD.
-///
-/// Note that not all parsed elements have an entry in `TagName`, the simpler
-/// ones might actually have an entry in `AttributeName` instead to simplify
-/// the parser's implementation.
-#[derive(PartialEq, Clone, Copy)]
-#[repr(C)]
-#[allow(clippy::upper_case_acronyms)]
-pub enum TagName {
-    /// Indicate an <MPD> node
-    /// These nodes are usually contained at the root of an MPD.
-    MPD = 1,
-
-    // -- Inside an <MPD> --
-    /// Indicate a <Period> node
-    Period = 2,
-
-    /// Indicate a <UTCTiming> node
-    UtcTiming = 3,
-
-    // -- Inside a <Period> --
-    /// Indicate an <AdaptationSet> node
-    AdaptationSet = 4,
-
-    /// Indicate an <EventStream> node
-    EventStream = 5,
-
-    /// Indicate an <Event> node.
-    /// These nodes are usually contained in <EventStream> elements.
-    EventStreamElt = 6,
-
-    // -- Inside an <AdaptationSet> --
-    /// Indicate a <Representation> node
-    Representation = 7,
-
-    /// Indicate an <Accessibility> node
-    Accessibility = 8,
-
-    /// Indicate a <ContentComponent> node
-    ContentComponent = 9,
-
-    /// Indicate a <ContentProtection> node
-    ContentProtection = 10,
-
-    /// Indicate an <EssentialProperty> node
-    EssentialProperty = 11,
-
-    /// Indicate a <Role> node
-    Role = 12,
-
-    /// Indicate a <SupplementalProperty> node
-    SupplementalProperty = 13,
-
-    // -- Inside various elements --
-    /// Indicate a <BaseURL> node
-    BaseURL = 15,
-
-    /// Indicate a <SegmentTemplate> node
-    SegmentTemplate = 16,
-
-    /// Indicate a <SegmentBase> node
-    SegmentBase = 17,
-
-    /// Indicate a <SegmentList> node
-    SegmentList = 18,
-
-    /// Indicate an <InbandEventStream> node
-    InbandEventStream = 19,
-
-    // -- Inside a <SegmentList> --
-    /// Indicate a <SegmentURL> node
-    SegmentUrl = 20,
-}
-
-#[derive(PartialEq, Clone, Copy)]
-#[repr(C)]
-pub enum AttributeName {
-    /// Describes the "id" attribute that can be found in many, many elements.
-    ///
-    /// It is reported as an UTF-8 sequence of bytes (through a pointer into
-    /// WebAssembly's memory and length).
-    ///
-    /// Among the elements concerned:
-    ///   - <MPD>
-    ///   - <Period>
-    ///   - <AdaptationSet>
-    ///   - <Representation>
-    ///   - <ContentComponent>
-    ///   - <Event> (from <EventStream> elements)
-    Id = 0,
-
-    /// Describes the "duration" attribute that can be found in multiple MPD
-    /// elements.
-    ///
-    /// It is reported as an f64, for easier JS manipulation.
-    ///
-    /// The Duration attribute can be found in:
-    ///   - <Period> elements. In that case this value will be reported as a
-    ///     number of seconds.
-    ///   - <SegmentTemplate> elements
-    ///   - <SegmentBase> elements
-    ///   - <Event> elements (from <EventStream> elements)
-    Duration = 1,
-
-    /// Describes the "profiles" attribute, found in `<MPD>` elements.
-    ///
-    /// It is reported as an UTF-8 sequence of bytes (through a pointer and
-    /// length into WebAssembly's memory).
-    Profiles = 2,
-
-    // AdaptationSet + Representation
-    AudioSamplingRate = 3,
-    Codecs = 4, // String
-    CodingDependency = 5,
-    FrameRate = 6,
-    Height = 7, // f64
-    Width = 8,  // f64
-    MaxPlayoutRate = 9,
-    MaxSAPPeriod = 10,
-    MimeType = 11, // f64
-    SegmentProfiles = 12,
-
-    // ContentProtection
-    ContentProtectionValue = 13,    // String
-    ContentProtectionKeyId = 14,    // ArrayBuffer
-    ContentProtectionCencPSSH = 15, // ArrayBuffer
-
-    // Various schemes (Accessibility) + EventStream + ContentProtection
-    SchemeIdUri = 16, // String
-
-    // Various schemes (Accessibility)
-    SchemeValue = 17, // String
-
-    // SegmentURL
-    MediaRange = 18, // [f64, f64]
-
-    // SegmentTimeline
-    SegmentTimeline = 19, // Vec<SElement>
-
-    // SegmentTemplate
-    StartNumber = 20, // f64
-
-    // SegmentTemplate + SegmentBase
-    AvailabilityTimeComplete = 22, // u8 (bool)
-    IndexRangeExact = 23,          // u8 (bool)
-    PresentationTimeOffset = 24,   // f64
-
-    // EventStream
-    EventPresentationTime = 25, // f64
-
-    // SegmentTemplate + SegmentBase + EventStream + EventStreamElt
-    TimeScale = 27, // f64
-
-    // SegmentURL + SegmentTemplate
-    Index = 28, // String
-
-    // Initialization
-    InitializationRange = 29, // [f64, f64]
-
-    // SegmentURL + SegmentTemplate + SegmentBase + Initialization
-    Media = 30,      // String
-    IndexRange = 31, // [f64, f64]
-
-    // Period + AdaptationSet + SegmentTemplate
-    BitstreamSwitching = 32, // u8 (bool)
-
-    // MPD
-    Type = 33,                       // String
-    AvailabilityStartTime = 34,      // f64
-    AvailabilityEndTime = 35,        // f64
-    PublishTime = 36,                // f64
-    MinimumUpdatePeriod = 37,        // f64
-    MinBufferTime = 38,              // f64
-    TimeShiftBufferDepth = 39,       // f64
-    SuggestedPresentationDelay = 40, // f64
-    MaxSegmentDuration = 41,         // f64
-    MaxSubsegmentDuration = 42,      // f64
-
-    // BaseURL + SegmentTemplate
-    AvailabilityTimeOffset = 43, // f64
-
-    // Period
-    Start = 45,        // f64
-    XLinkHref = 46,    // String
-    XLinkActuate = 47, // String
-
-    // AdaptationSet
-    Group = 48,
-    MaxBandwidth = 49, // f64
-    MaxFrameRate = 50, // f64
-    MaxHeight = 51,    // f64
-    MaxWidth = 52,     // f64
-    MinBandwidth = 53, // f64
-    MinFrameRate = 54, // f64
-    MinHeight = 55,    // f64
-    MinWidth = 56,     // f64
-    SelectionPriority = 57,
-    SegmentAlignment = 58,
-    SubsegmentAlignment = 59,
-
-    // AdaptationSet + ContentComponent
-    Language = 60,    // String
-    ContentType = 61, // String
-    Par = 62,
-
-    // Representation
-    Bitrate = 63, // f64
-
-    Text = 64,
-    QualityRanking = 65,
-    Location = 66,
-
-    InitializationMedia = 67,
-
-    /// Describes an encountered "mediaPresentationDuration" attribute, as found
-    /// in `<MPD>` elements.
-    ///
-    /// This value has been converted into seconds, as an f64.
-    MediaPresentationDuration = 68,
-
-    /// Describes the byte range (end not included) of an encountered `<Event>`
-    /// element in the whole MPD.
-    ///
-    /// This can be useful to re-construct the whole element on the JS-sid.
-    ///
-    /// It is reported as an array of two f64 values.
-    /// The first number indicating the starting range (included).
-    /// The second indicating the ending range (non-included).
-    EventStreamEltRange = 69,
-
-    /// Describes an XML namespace coming from either a `<MPD>` element, a
-    /// `<Period> element or a `<EventStream>` elements, as those are the three
-    /// parent tags of potential `<Event>` elements.
-    ///
-    /// It is reported as the concatenation of four values:
-    ///
-    ///   - In the four first bytes: The length of the namespace's name (the
-    ///     part in the XML attribute just after "xmlns:"), as a big endian
-    ///     unsigned 32 bit integer
-    ///
-    ///   - The namespace's name (the part coming after "xmlns:" in the
-    ///     attribute's name), as an UTF-8 encoded string.
-    ///     The length of this attribute is indicated by the preceding four
-    ///     bytes.
-    ///
-    ///   - As the next four bytes: The length of the namespace's value (the
-    ///     corresponding XML attribute's value), as a big endian
-    ///     unsigned 32 bit integer
-    ///
-    ///   - The namespace's value (the value of the corresponding XML
-    ///     attribute), as an UTF-8 encoded string.
-    ///     The length of this attribute is indicated by the preceding four
-    ///     bytes.
-    ///
-    /// This special Attribute was needed because we need those namespaces to be
-    /// able to communicate `<Event>` property under a JavaScript's Element
-    /// format: the browser's `DOMParser` API needs to know all potential
-    /// namespaces that will appear in it.
-    Namespace = 70,
-
-    Label = 71, // String
-
-    ServiceLocation = 72, // String
-
-    // SegmentTemplate
-    EndNumber = 76, // f64
-
-    SupplementalCodecs = 77 // string
-}
-
-impl TagName {
-    /// Signal a new tag opening to the application
-    pub fn report_tag_open(self) {
-        debug_assert!(self as u64 <= u8::MAX as u64);
-
-        // UNSAFE: We're using FFI, but there should be no risk at all here
-        unsafe { onTagOpen(self) };
-    }
-
-    /// Signal that a previously-open tag closed to the application
-    pub fn report_tag_close(self) {
-        debug_assert!(self as u64 <= u8::MAX as u64);
-
-        // UNSAFE: We're using FFI, but there should be no risk at all here
-        unsafe { onTagClose(self) };
-    }
-}
-
-use crate::reportable::ReportableAttribute;
-use crate::utils;
-
-impl AttributeName {
-    #[inline(always)]
-    pub fn report<T: ReportableAttribute>(self, val: T) {
-        val.report_as_attr(self)
-    }
-
-    pub fn try_report_as_string(self, attr: &quick_xml::events::attributes::Attribute) {
-        match attr.unescape_value() {
-            Ok(val) => self.report(val),
-            Err(_) => ParsingError("Could not escape original value".to_owned()).report_err(),
-        }
-    }
-
-    pub fn try_report_as_f64(self, attr: &quick_xml::events::attributes::Attribute) {
-        match utils::parse_f64(&attr.value) {
-            Ok(val) => self.report(val),
-            Err(error) => error.report_err(),
-        }
-    }
-
-    pub fn try_report_as_iso_8601_duration(self, attr: &quick_xml::events::attributes::Attribute) {
-        match utils::parse_iso_8601_duration(&attr.value) {
-            Ok(val) => self.report(val),
-            Err(error) => error.report_err(),
-        }
-    }
-
-    pub fn try_report_as_u64(self, attr: &quick_xml::events::attributes::Attribute) {
-        match utils::parse_u64(&attr.value) {
-            Ok(val) => self.report(val as f64),
-            Err(error) => error.report_err(),
-        }
-    }
-
-    pub fn try_report_as_u64_or_bool(self, attr: &quick_xml::events::attributes::Attribute) {
-        match utils::parse_u64_or_bool(&attr.value) {
-            Ok(val) => self.report(val),
-            Err(error) => error.report_err(),
-        }
-    }
-
-    pub fn try_report_as_bool(self, attr: &quick_xml::events::attributes::Attribute) {
-        match utils::parse_bool(&attr.value) {
-            Ok(val) => self.report(val),
-            Err(error) => error.report_err(),
-        }
-    }
-
-    pub fn try_report_as_range(self, attr: &quick_xml::events::attributes::Attribute) {
-        match utils::parse_byte_range(&attr.value) {
-            Ok(val) => self.report(val),
-            Err(error) => error.report_err(),
-        }
-    }
-
-    pub fn try_report_as_key_value(
-        self,
-        key: &[u8],
-        value: &quick_xml::events::attributes::Attribute,
-    ) {
-        match value.unescape_value() {
-            Ok(val) => self.report((key, val)),
-            Err(_) => ParsingError("Could not escape original value".to_owned()).report_err(),
-        }
-    }
-}