Skip to content

Commit 10617da

Browse files
JoaquinBChJoaquinBCh
committed
lib readme update
1 parent 5d657d4 commit 10617da

File tree

2 files changed

+156
-151
lines changed

2 files changed

+156
-151
lines changed

‎README.md‎

Lines changed: 141 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,38 +1,166 @@
11
<p align="center">
2-
<img height="128px" src="https://github.com/kixelated/moq-js/blob/main/.github/logo.svg" alt="Media over QUIC">
2+
<img height="128px" src="https://github.com/englishm/moq-js/blob/main/.github/logo.svg" alt="Media over QUIC">
33
</p>
44

5+
# Media over QUIC (MoQ) Player
6+
57
Media over QUIC (MoQ) is a live media delivery protocol utilizing QUIC streams.
68
See the [MoQ working group](https://datatracker.ietf.org/wg/moq/about/) for more information.
79

8-
This repository contains the a web library for MoQ.
9-
It uses the browser APIs such as WebTransport and WebCodecs to support both contribution and distribution.
10-
Check out [quic.video](https://quic.video) for a demo or [run it locally](https://github.com/kixelated/quic.video) as a UI.
10+
This repository provides a **web library for MoQ**. It uses browser APIs such as **WebTransport** and **WebCodecs** to support both contribution and distribution over MoQ.
11+
12+
> **Note**: This library currently focuses on the **client side**. You’ll need a MoQ server or relay, such as [moq-rs](https://github.com/englishm/moq-rs) (for local usage).
13+
14+
This library offers **two main approaches** to playing MoQ streams in a browser:
1115

12-
This is a client only.
13-
You'll either need to run a local server using [moq-rs](https://github.com/kixelated/moq-rs) or use a public server such as [relay.quic.video](https://quic.video/relay).
16+
1. **Web Component** – `<video-moq>` with simple built-in controls.
17+
2. **Simple Player** – A `Player` class that handles rendering and playback logic without built-in UI.
1418

15-
Join the [Discord](https://discord.gg/FCYF3p99mr) for updates and discussion.
19+
---
1620

17-
## Setup
21+
## Installation
1822

19-
Install the dependencies with `npm`:
23+
Install the library from npm:
2024

2125
```bash
22-
npm install
26+
npm install moq-player
27+
```
28+
29+
Or include via a `<script>` tag (for the IIFE build):
30+
31+
```html
32+
<script src="https://cdn.jsdelivr.net/npm/package@latest/dist/moq-player.iife.js"></script>
33+
```
34+
35+
## Usage
36+
37+
### Web Component: `<video-moq>`
38+
39+
```html
40+
<video-moq
41+
src="https://example.com/my-moq-stream?namespace=demo"
42+
fingerprint="https://example.com/fingerprint"
43+
width="640"
44+
muted
45+
controls
46+
></video-moq>
2347
```
2448

49+
The built-in controls are basic. If you want more advanced controls or custom styling, see the [Styling & Media Chrome](#styling--media-chrome) section or our samples.
50+
51+
### Simple Player
52+
53+
If you’d prefer to implement your own UI or integrate the player logic differently, use the class-based Player:
54+
55+
```javascript
56+
import { Player } from "moq-player";
57+
58+
async function initPlayer() {
59+
const canvas = document.getElementById("my-canvas");
60+
const player = await Player.create({
61+
url: "https://example.com/my-moq-stream",
62+
fingerprint: "https://example.com/fingerprint",
63+
namespace: "demo",
64+
canvas,
65+
});
66+
67+
player.play();
68+
// Implement your own play/pause buttons, volume sliders, etc.
69+
}
70+
```
71+
72+
## Events
73+
74+
Both the Web Component and the Class-Based Player emit a series of events to help track playback state:
75+
76+
- `play`
77+
- `pause`
78+
- `loadeddata`
79+
- `volumechange`
80+
- `unsubscribestared`
81+
- `unsubscribedone`
82+
- `subscribestared`
83+
- `subscribedone`
84+
- `waitingforkeyframe`
85+
- `timeupdate`
86+
87+
You can listen to these events in the usual way. For example:
88+
89+
```javascript
90+
const videoMoq = document.querySelector("video-moq");
91+
videoMoq.addEventListener("play", () => {
92+
console.log("Playback started!");
93+
});
94+
```
95+
96+
See `samples/event-handling` for complete examples.
97+
98+
## Styling & Media Chrome
99+
100+
When using the `<video-moq>` element, you can style it in various ways:
101+
102+
- **Media Chrome:** Integrate `<video-moq>` inside a `<media-controller>` and use `<media-play-button>`, `<media-time-range>`, and other controls. See `samples/media-chrome` for an example.
103+
104+
```html
105+
<script type="module" src="https://cdn.jsdelivr.net/npm/media-chrome@4/+esm"></script>
106+
<media-controller>
107+
<video-moq slot="media" src="..." controls></video-moq>
108+
<media-play-button></media-play-button>
109+
<media-mute-button></media-mute-button>
110+
111+
<!-- more controls... -->
112+
</media-controller>
113+
```
114+
115+
- **player.style:** You can also use custom themes from [player.style](https://player.style/) to style the player. See `samples/media-chrome` for a working example.
116+
117+
```html
118+
<script type="module" src="https://cdn.jsdelivr.net/npm/player.style/x-mas/+esm"></script>
119+
<media-theme-x-mas>
120+
<video-moq
121+
src="https://localhost:4443?namespace=bbb"
122+
fingerprint="https://localhost:4443/fingerprint"
123+
width="640px"
124+
slot="media"
125+
></video-moq>
126+
</media-theme-x-mas>
127+
```
128+
129+
## Samples
130+
131+
The `samples/` directory demonstrates:
132+
133+
- **Web Component Basic** – A simple `<video-moq>` usage.
134+
- **Web Component Advanced** – Using the component as an ES module.
135+
- **Media Chrome** – Integrating `<video-moq>` with [player.style](https://player.style/) custom themes.
136+
- **Simple Player** – Using the class-based Player without built-in controls.
137+
- **Event Handling** – Listening for playback and subscription events in detail.
138+
25139
## Development
26140

27-
Run the development web server:
141+
- Install dependencies
142+
143+
```
144+
npm install
145+
```
146+
147+
- Run the dev server for local testing:
28148

29149
```bash
30150
npm run dev
31151
```
32152

153+
In [localhost:3000](http://localhost:3000/) you will have the samples running.
154+
33155
## License
34156

35157
Licensed under either:
36158

37-
- Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
38-
- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
159+
- Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
160+
- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
161+
162+
## Community & Support
163+
164+
- Join our [Discord](https://discord.gg/FCYF3p99mr) for updates and discussion.
165+
- File issues or suggestions via GitHub Issues.
166+
- Pull requests are welcome!

‎lib/README.md‎

Lines changed: 15 additions & 138 deletions
Original file line numberDiff line numberDiff line change
@@ -1,166 +1,43 @@
1-
<p align="center">
2-
<img height="128px" src="https://github.com/englishm/moq-js/blob/main/.github/logo.svg" alt="Media over QUIC">
3-
</p>
4-
5-
# Media over QUIC (MoQ) Player
1+
# Media over QUIC
62

73
Media over QUIC (MoQ) is a live media delivery protocol utilizing QUIC streams.
8-
See the [MoQ working group](https://datatracker.ietf.org/wg/moq/about/) for more information.
9-
10-
This repository provides a **web library for MoQ**. It uses browser APIs such as **WebTransport** and **WebCodecs** to support both contribution and distribution over MoQ.
11-
12-
> **Note**: This library currently focuses on the **client side**. You’ll need a MoQ server or relay, such as [moq-rs](https://github.com/englishm/moq-rs) (for local usage), to stream live content.
13-
14-
This library offers **two main approaches** to playing MoQ streams in a browser:
15-
16-
1. **Web Component** – `<video-moq>` with simple built-in controls.
17-
2. **Simple Player** – A `Player` class that handles rendering and playback logic without built-in UI.
4+
See the [Warp draft](https://datatracker.ietf.org/doc/draft-lcurley-warp/).
185

19-
---
6+
## Install
207

21-
## Installation
8+
To install dependencies:
229

23-
Install the library from npm:
24-
25-
```bash
26-
npm install moq-player
2710
```
28-
29-
Or include via a `<script>` tag (for the IIFE build):
30-
31-
```html
32-
<script src="https://cdn.jsdelivr.net/npm/package@latest/dist/moq-player.iife.js"></script>
33-
```
34-
35-
## Usage
36-
37-
### Web Component: `<video-moq>`
38-
39-
```html
40-
<video-moq
41-
src="https://example.com/my-moq-stream?namespace=demo"
42-
fingerprint="https://example.com/fingerprint"
43-
width="640"
44-
muted
45-
controls
46-
></video-moq>
47-
```
48-
49-
The built-in controls are basic. If you want more advanced controls or custom styling, see the [Styling & Media Chrome](#styling--media-chrome) section or our samples.
50-
51-
### Simple Player
52-
53-
If you’d prefer to implement your own UI or integrate the player logic differently, use the class-based Player:
54-
55-
```javascript
56-
import { Player } from "moq-player"
57-
58-
async function initPlayer() {
59-
const canvas = document.getElementById("my-canvas")
60-
const player = await Player.create({
61-
url: "https://example.com/my-moq-stream",
62-
fingerprint: "https://example.com/fingerprint",
63-
namespace: "demo",
64-
canvas,
65-
})
66-
67-
player.play()
68-
// Implement your own play/pause buttons, volume sliders, etc.
69-
}
70-
```
71-
72-
## Events
73-
74-
Both the Web Component and the Class-Based Player emit a series of events to help track playback state:
75-
76-
- `play`
77-
- `pause`
78-
- `loadeddata`
79-
- `volumechange`
80-
- `unsubscribestared`
81-
- `unsubscribedone`
82-
- `subscribestared`
83-
- `subscribedone`
84-
- `waitingforkeyframe`
85-
- `timeupdate`
86-
87-
You can listen to these events in the usual way. For example:
88-
89-
```javascript
90-
const videoMoq = document.querySelector("video-moq")
91-
videoMoq.addEventListener("play", () => {
92-
console.log("Playback started!")
93-
})
11+
npm install
9412
```
9513

96-
See `samples/event-handling` for complete examples.
97-
98-
## Styling & Media Chrome
99-
100-
When using the `<video-moq>` element, you can style it in various ways:
14+
## Build
10115

102-
- **Media Chrome:** Integrate `<video-moq>` inside a `<media-controller>` and use `<media-play-button>`, `<media-time-range>`, and other controls. See `samples/media-chrome` for an example.
16+
To generate the builds:
10317

104-
```html
105-
<script type="module" src="https://cdn.jsdelivr.net/npm/media-chrome@4/+esm"></script>
106-
<media-controller>
107-
<video-moq slot="media" src="..." controls></video-moq>
108-
<media-play-button></media-play-button>
109-
<media-mute-button></media-mute-button>
110-
111-
<!-- more controls... -->
112-
</media-controller>
11318
```
114-
115-
- **player.style:** You can also use custom themes from [player.style](https://player.style/) to style the player. See `samples/media-chrome` for a working example.
116-
117-
```html
118-
<script type="module" src="https://cdn.jsdelivr.net/npm/player.style/x-mas/+esm"></script>
119-
<media-theme-x-mas>
120-
<video-moq
121-
src="https://localhost:4443?namespace=bbb"
122-
fingerprint="https://localhost:4443/fingerprint"
123-
width="640px"
124-
slot="media"
125-
></video-moq>
126-
</media-theme-x-mas>
19+
npm run build
12720
```
12821

129-
## Samples
130-
131-
The `samples/` directory demonstrates:
22+
Generated builds:
13223

133-
- **Web Component Basic** – A simple `<video-moq>` usage.
134-
- **Web Component Advanced** – Using the component as an ES module.
135-
- **Media Chrome** – Integrating `<video-moq>` with [player.style](https://player.style/) custom themes.
136-
- **Simple Player** – Using the class-based Player without built-in controls.
137-
- **Event Handling** – Listening for playback and subscription events in detail.
24+
- **IIFE:** `dist/moq-player.iife.js` & `dist/moq-simple-player.iife.js` – for direct browser usage via `<script>` tags.
25+
- **ESM:** `dist/moq-player.esm.js` & `dist/moq-simple-player.esm.js` – for module-based usage in modern bundlers.
26+
- **Type Definitions:** `dist/types/moq-player.d.ts` – TypeScript declarations for type-safe development.
13827

139-
## Development
28+
## Develop
14029

141-
- Install dependencies
30+
To start the development build process (with Rollup):
14231

14332
```
144-
npm install
145-
```
146-
147-
- Run the dev server for local testing:
148-
149-
```bash
15033
npm run dev
15134
```
15235

153-
In [localhost:3000](http://localhost:3000/) you will have the samples running.
36+
This build the library continuously as you make changes.
15437

15538
## License
15639

15740
Licensed under either:
15841

15942
- Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
16043
- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
161-
162-
## Community & Support
163-
164-
- Join our [Discord](https://discord.gg/FCYF3p99mr) for updates and discussion.
165-
- File issues or suggestions via GitHub Issues.
166-
- Pull requests are welcome!

0 commit comments

Comments
 (0)