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

feat(streams)!: Node.js Buffer+Stream -> JS Uint8Array/Web Streams API #1069

Merged
merged 1 commit into from
Jan 10, 2025

Conversation

steabert
Copy link
Member

@steabert steabert commented Dec 5, 2024

Replaces use of Buffer with Uint8Array. The latter is now widely
supported and available in Node.js and Browsers.
Notable differences:

  • Buffer.slice(...) has been replaced with Uint8Array.subarray(...)
    as that is the actual behaviour of the original method
    (Uint8Array.slice(...) makes a copy).
  • Converting to and from strings is handled by TextEncoder/TextDecoder
  • Converting to and from differently sized big-endian integers is
    handled by using DataView

Replaces use of Node.js Stream module with Web Streams API.
Since the latter is substantially different in some important details
regarding stream pipelining, the way pipelines are built are redefined.
The component concept as module blocks is removed and instead the
components themselves expose streams that can be combined together.
The pipelines are then simple stream compositions.

Because this is a major (breaking) change, it's done in concert with
other planned improvements that are also breaking changes (see section
below for details).

Improvements:

  • replacing the Node.js stream module with Web Streams API removes
    the dependency on the (legacy) stream-browserify package and
    results in a much smaller library (bundle) size, so there is no longer
    a need for a separate "light" version
  • debug package replaced by custom internal logging utilities
    (allowing proper ES module support) Fixes Cannot use versions >v11.2.0 in a pure ESM project #990, Closes Replace debug with tslog #992
  • added audio test signal to the H.264 test

Refactoring:

  • RTSP session and parser are combined in a single component and the
    session controller has been rewritten as a request-response flow.
    An async start method starts the streams and returns SDP + range.
  • RTP depay is combined into a single component that detects
    the proper format based on payloadType, and allows registering
    a "peeker" that can inspect messages (instead of having to insert
    an extra transform stream)
  • Extended use of TypeScript in areas where this was lacking

BREAKING CHANGES:

  • No support for CommonJS:
    • Node.js has support for ES modules
    • Browsers have support for ES modules, but you can also still
      use the IIFE global variable, or use a bundler (all of which
      support ES modules)
  • No distinction between Node.js/Browser:
    • The library targets mainly Browser, so some things rely on window
      and expect it to be present, however most things work both platforms.
    • Node-only pipelines are removed, these are trivial to re-implement
      with Web Streams API if necessary. The CLI player has its own TCP
      source for that reason (replacing the CliXyz pipelines).
  • The generic "component" and "pipeline" classes were removed:
    • Components extend Web Streams API instead
    • Pipelines rely on pipeTo/pipeThrough composition and a start
      method to initiate flow of data.
  • Some public methods on pipelines have been removed (refer to their
    type for details) in cases where a simple alternative is available, or
    check the examples to see how to modify usage. There are less pipelines
    but they are more versatile, with accessible readonly components.
    In general, promises/async methods are preferred over callbacks.

Co-authored-by: Rikard Tegnander [email protected]
Co-authored-by: Victor Ingvarsson [email protected]

@steabert steabert force-pushed the next branch 2 times, most recently from 92f6b03 to ae57930 Compare December 5, 2024 09:12
@steabert steabert self-assigned this Dec 5, 2024
@steabert steabert force-pushed the next branch 5 times, most recently from a9621ea to b03acc2 Compare December 12, 2024 11:01
@steabert steabert force-pushed the next branch 3 times, most recently from 898c429 to e146e60 Compare December 24, 2024 12:38
@steabert steabert force-pushed the next branch 8 times, most recently from 4589747 to fa9f1b8 Compare January 8, 2025 10:35
@steabert steabert marked this pull request as ready for review January 8, 2025 10:40
@steabert steabert requested review from Tigge and rikteg as code owners January 8, 2025 10:40
lekoaf
lekoaf previously approved these changes Jan 9, 2025
Copy link
Member

@lekoaf lekoaf left a comment

Choose a reason for hiding this comment

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

Well, overall the code looks fine. I trust that you test it thoroughly.

@steabert
Copy link
Member Author

steabert commented Jan 9, 2025

@lekoaf @rikteg I fixed all comments (even though I didn't always write a reply), if not then I responded why.

@steabert steabert changed the title Replace Node.js Buffer and Stream API with Uint8Array and Web Streams API feat(streams)!: Node.js Buffer+Stream -> JS Uint8Array/Web Streams API Jan 9, 2025
@steabert steabert mentioned this pull request Jan 9, 2025
Replaces use of `Buffer` with `Uint8Array`. The latter is now widely
supported and available in Node.js and Browsers.
Notable differences:
- `Buffer.slice(...)` has been replaced with `Uint8Array.subarray(...)`
  as that is the actual behaviour of the original method
  (`Uint8Array.slice(...)` makes a copy).
- Converting to and from strings is handled by `TextEncoder`/`TextDecoder`
- Converting to and from differently sized big-endian integers is
  handled by using `DataView`

Replaces use of Node.js Stream module with Web Streams API.
Since the latter is substantially different in some important details
regarding stream pipelining, the way pipelines are built are redefined.
The component concept as module blocks is removed and instead the
components themselves expose streams that can be combined together.
The pipelines are then simple stream compositions.

Because this is a major (breaking) change, it's done in concert with
other planned improvements that are also breaking changes (see section
below for details).

Improvements:
- replacing the Node.js stream module with Web Streams API removes
  the dependency on the (legacy) stream-browserify package and
  results in a much smaller library (bundle) size, so there is no longer
  a need for a separate "light" version
- `debug` package replaced by custom internal logging utilities
  (allowing proper ES module support) Fixes #990, Closes #992
- added audio test signal to the H.264 test

Refactoring:
- RTSP session and parser are combined in a single component and the
  session controller has been rewritten as a request-response flow.
  An async `start` method starts the streams and returns SDP + range.
- RTP depay is combined into a single component that detects
  the proper format based on payloadType, and allows registering
  a "peeker" that can inspect messages (instead of having to insert
  an extra transform stream)
- Extended use of TypeScript in areas where this was lacking

BREAKING CHANGES:
- No support for CommonJS:
  - Node.js has support for ES modules
  - Browsers have support for ES modules, but you can also still
    use the IIFE global variable, or use a bundler (all of which
    support ES modules)
- No distinction between Node.js/Browser:
  - The library targets mainly Browser, so some things rely on `window`
    and expect it to be present, however most things work both platforms.
  - Node-only pipelines are removed, these are trivial to re-implement
    with Web Streams API if necessary. The CLI player has its own TCP
    source for that reason (replacing the CliXyz pipelines).
- The generic "component" and "pipeline" classes were removed:
  - Components extend Web Streams API instead
  - Pipelines rely on `pipeTo`/`pipeThrough` composition and a `start`
    method to initiate flow of data.
- Some public methods on pipelines have been removed (refer to their
  type for details) in cases where a simple alternative is available, or
  check the examples to see how to modify usage. There are less pipelines
  but they are more versatile, with accessible readonly components.
  In general, promises/async methods are preferred over callbacks.

Co-authored-by: Rikard Tegnander <[email protected]>
Co-authored-by: Victor Ingvarsson <[email protected]>
@steabert steabert merged commit 8114f37 into main Jan 10, 2025
8 checks passed
@steabert steabert deleted the next branch January 10, 2025 13:39
@oskbor
Copy link

oskbor commented Jan 10, 2025

lgtm, ship it

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Replace debug with tslog Cannot use versions >v11.2.0 in a pure ESM project
5 participants