@creekx/web 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,22 @@
1
+ /**
2
+ * `<creekx-player>`: the player as one tag, for any page and any framework.
3
+ *
4
+ * <script type="module" src="creekx-web.js"></script>
5
+ * <creekx-player server="https://live.example.com" stream="..." code="..."></creekx-player>
6
+ *
7
+ * Starts muted, because browsers refuse to start sound by themselves; the controls unmute it.
8
+ * Tells the page what is happening with a `creekx-state` event: `{ state, mode, why }`.
9
+ */
10
+ import { type Player } from './player.js';
11
+ export declare class CreekXPlayerElement extends HTMLElement {
12
+ static readonly observedAttributes: readonly ["server", "stream", "code", "mode"];
13
+ private player;
14
+ private video;
15
+ /** The player itself, for `setMode` and friends. Undefined until it has what it needs. */
16
+ get current(): Player | undefined;
17
+ connectedCallback(): void;
18
+ disconnectedCallback(): void;
19
+ attributeChangedCallback(name: string, before: string | null, after: string | null): void;
20
+ private begin;
21
+ }
22
+ //# sourceMappingURL=element.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"element.d.ts","sourceRoot":"","sources":["../src/element.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAgB,KAAK,MAAM,EAAiB,MAAM,aAAa,CAAC;AAIvE,qBAAa,mBAAoB,SAAQ,WAAW;IAClD,MAAM,CAAC,QAAQ,CAAC,kBAAkB,gDAAY;IAC9C,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,KAAK,CAA+B;IAE5C,0FAA0F;IAC1F,IAAI,OAAO,IAAI,MAAM,GAAG,SAAS,CAEhC;IAED,iBAAiB,IAAI,IAAI;IAgBzB,oBAAoB,IAAI,IAAI;IAK5B,wBAAwB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IASzF,OAAO,CAAC,KAAK;CAkBd"}
@@ -0,0 +1,12 @@
1
+ /**
2
+ * @creekx/web -- creekX for web pages: play a stream in real time with HLS behind it
3
+ * (`createPlayer`, `<creekx-player>`), and go live from a browser (`publish`). Also the
4
+ * WebRTC code the creekX app itself runs, so a fix reaches both.
5
+ */
6
+ export * from './element.js';
7
+ export * from './player.js';
8
+ export * from './publisher.js';
9
+ export * from './whep.js';
10
+ export { sessionUrl, gathered, preferH264, startWhip, whipProblem } from './whip.js';
11
+ export type { WhipOptions } from './whip.js';
12
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACrF,YAAY,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC"}
@@ -0,0 +1,36 @@
1
+ /**
2
+ * Play a creekX stream on any web page: real time (WebRTC) where the network allows it, and
3
+ * HLS by itself where it does not, so a viewer always gets a picture.
4
+ *
5
+ * What a watch link or a play token is enough for: no API key on the page, ever. The same
6
+ * rule as the creekX app's own player: a slow start is not a blocked network, so only a real
7
+ * connection failure gives up on real time, after real patience.
8
+ */
9
+ export type PlayMode = 'webrtc' | 'hls';
10
+ export type PlayerState = 'waiting' | 'connecting' | 'playing' | 'reconnecting' | 'stopped';
11
+ export interface PlayerOptions {
12
+ /** Your creekX server, e.g. "https://live.example.com". Empty: this page's own. */
13
+ readonly server: string;
14
+ readonly stream: string;
15
+ /** The code from the stream's watch link, or a play token from `streams.createToken`. */
16
+ readonly code: string;
17
+ readonly video: HTMLVideoElement;
18
+ /** How to start. Default `webrtc`, which moves to HLS by itself when it cannot connect. */
19
+ readonly mode?: PlayMode;
20
+ onState?(state: PlayerState, detail: {
21
+ readonly mode: PlayMode;
22
+ readonly why?: string;
23
+ }): void;
24
+ }
25
+ export interface Player {
26
+ readonly mode: PlayMode;
27
+ readonly state: PlayerState;
28
+ setMode(mode: PlayMode): void;
29
+ stop(): void;
30
+ }
31
+ /** How long a real-time start may take before HLS: starting is on demand (see the app's player). */
32
+ export declare const START_WITHIN_MS = 90000;
33
+ /** How long the browser may take to connect, once the server has answered. */
34
+ export declare const CONNECT_WITHIN_MS = 20000;
35
+ export declare function createPlayer(options: PlayerOptions): Player;
36
+ //# sourceMappingURL=player.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"player.d.ts","sourceRoot":"","sources":["../src/player.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,KAAK,CAAC;AACxC,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,YAAY,GAAG,SAAS,GAAG,cAAc,GAAG,SAAS,CAAC;AAE5F,MAAM,WAAW,aAAa;IAC5B,mFAAmF;IACnF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,yFAAyF;IACzF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;IACjC,2FAA2F;IAC3F,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC;IACzB,OAAO,CAAC,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;QAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CAChG;AAED,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC9B,IAAI,IAAI,IAAI,CAAC;CACd;AAqBD,oGAAoG;AACpG,eAAO,MAAM,eAAe,QAAS,CAAC;AACtC,8EAA8E;AAC9E,eAAO,MAAM,iBAAiB,QAAS,CAAC;AAMxC,wBAAgB,YAAY,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,CA8N3D"}
@@ -0,0 +1,26 @@
1
+ /**
2
+ * Go live from a web page: the viewer's camera, or anything in a MediaStream, by WHIP.
3
+ *
4
+ * Make a publish token on your server (`streams.createToken(id, { use: 'publish', ... })`, or
5
+ * POST /v1/streams/{id}/tokens) and hand the page its `publish.browser`: never an API key or
6
+ * the stream's own key on a page. Needs https, which browsers require for a camera.
7
+ */
8
+ import { type WhipSession, type WhipState } from './whip.js';
9
+ export type { WhipSession, WhipState };
10
+ export interface PublishOptions {
11
+ /** `whipUrl` and `bearerToken` come from the token answer's `publish.browser`. */
12
+ readonly whipUrl: string;
13
+ readonly bearerToken: string;
14
+ /** What to send. Default: this device's camera and microphone, which the browser asks for. */
15
+ readonly stream?: MediaStream;
16
+ /** Most bits per second for the picture. Default 2.5 Mbps. */
17
+ readonly maxVideoBitrate?: number;
18
+ readonly iceServers?: readonly RTCIceServer[];
19
+ onState?(state: WhipState): void;
20
+ }
21
+ export declare const DEFAULT_MAX_VIDEO_BITRATE = 2500000;
22
+ export interface Publisher extends WhipSession {
23
+ readonly stream: MediaStream;
24
+ }
25
+ export declare function publish(options: PublishOptions): Promise<Publisher>;
26
+ //# sourceMappingURL=publisher.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"publisher.d.ts","sourceRoot":"","sources":["../src/publisher.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAa,KAAK,WAAW,EAAE,KAAK,SAAS,EAAE,MAAM,WAAW,CAAC;AAExE,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,CAAC;AAEvC,MAAM,WAAW,cAAc;IAC7B,kFAAkF;IAClF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,8FAA8F;IAC9F,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,8DAA8D;IAC9D,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IAC9C,OAAO,CAAC,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,CAAC;CAClC;AAED,eAAO,MAAM,yBAAyB,UAAY,CAAC;AAEnD,MAAM,WAAW,SAAU,SAAQ,WAAW;IAC5C,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B;AAED,wBAAsB,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,SAAS,CAAC,CAmCzE"}
package/dist/whep.d.ts ADDED
@@ -0,0 +1,47 @@
1
+ /**
2
+ * Watching in real time: WebRTC, by WHEP -- one HTTP offer, one answer, then picture and
3
+ * sound arrive under a second behind, where HLS runs a few seconds behind. The mirror of
4
+ * going live from a browser (whip.ts), receiving instead of sending.
5
+ *
6
+ * The pass comes from the API (`/v1/watch/<id>/<code>/webrtc`, or `/v1/streams/<id>/webrtc`
7
+ * for the owner) and lasts minutes: a reconnect asks for a new one. The live server
8
+ * checks it itself (decideLiveAccess), so the address alone shows nobody anything.
9
+ *
10
+ * What plays: a stream sent from a browser as it is (H.264 and Opus already); anything
11
+ * else through its real-time copy, which the live server converts while somebody watches
12
+ * so (spike 13: OBS's usual output shows nothing over WebRTC, and AAC is silent).
13
+ */
14
+ export type WhepState = 'connecting' | 'playing' | 'reconnecting' | 'failed' | 'ended';
15
+ export interface WhepSession {
16
+ readonly state: WhepState;
17
+ /** Hang up: tell the server (so its converter can stop), then close. */
18
+ stop(): void;
19
+ }
20
+ export interface WhepOptions {
21
+ readonly whepUrl: string;
22
+ readonly pass: string;
23
+ readonly video: HTMLVideoElement;
24
+ /**
25
+ * TURN the owner configured, for networks that block UDP. Without it the browser still
26
+ * tries the live server's TCP port when UDP fails (spike 25).
27
+ */
28
+ readonly iceServers?: readonly RTCIceServer[];
29
+ onState(state: WhepState): void;
30
+ }
31
+ /** A refused offer, with what the live server answered: 0 when it could not be reached. */
32
+ export declare class WhepRefused extends Error {
33
+ readonly status: number;
34
+ constructor(message: string, status: number);
35
+ }
36
+ /**
37
+ * What a refused offer's status really is. The live server answers 400 for two things that are
38
+ * not an offer it cannot use, and are worth asking again: a real-time copy that missed its start
39
+ * limit ("source of path ... has timed out"), and an offer that met the last viewer's connection
40
+ * still closing ("InvalidStateError: connection closed", caught switching HLS to WebRTC on a busy
41
+ * machine by `pnpm webrtc:check --busy`).
42
+ */
43
+ export declare function refusedStatus(status: number, said: string): number;
44
+ /** What a refused offer means, in words a viewer can act on. */
45
+ export declare function whepProblem(status: number): string;
46
+ export declare function startWhep(options: WhepOptions): Promise<WhepSession>;
47
+ //# sourceMappingURL=whep.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"whep.d.ts","sourceRoot":"","sources":["../src/whep.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,MAAM,MAAM,SAAS,GAAG,YAAY,GAAG,SAAS,GAAG,cAAc,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEvF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,wEAAwE;IACxE,IAAI,IAAI,IAAI,CAAC;CACd;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;IACjC;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IAC9C,OAAO,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,CAAC;CACjC;AAED,2FAA2F;AAC3F,qBAAa,WAAY,SAAQ,KAAK;IAGlC,QAAQ,CAAC,MAAM,EAAE,MAAM;gBADvB,OAAO,EAAE,MAAM,EACN,MAAM,EAAE,MAAM;CAI1B;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAElE;AAED,gEAAgE;AAChE,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAWlD;AAED,wBAAsB,SAAS,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CA6E1E"}
package/dist/whip.d.ts ADDED
@@ -0,0 +1,51 @@
1
+ /**
2
+ * Going live from this browser (L5): WHIP -- one HTTP offer, one answer -- to the live
3
+ * server's browser entry for this creator (spike 12). The server converts the browser's
4
+ * sound to what platforms take and sends the live on like any other; this file only has to
5
+ * connect, report how the connection is doing, and hang up properly.
6
+ *
7
+ * Measured in spike 12 with Chromium: accepted in ~0.6 s, H.264 negotiated when put first,
8
+ * the server asking for a keyframe every ~2 s -- the spacing platforms ask for. The key
9
+ * travels as a bearer token, fetched (and audited) when the creator presses Go live, and
10
+ * kept in memory only.
11
+ */
12
+ export type WhipState = 'connecting' | 'live' | 'reconnecting' | 'failed' | 'ended';
13
+ export interface WhipSession {
14
+ readonly state: WhipState;
15
+ /** Hang up: tell the server, then close. */
16
+ stop(): Promise<void>;
17
+ /** Hang up without waiting, for a page that is closing: the goodbye outlives the page. */
18
+ stopNow(): void;
19
+ }
20
+ export interface WhipOptions {
21
+ readonly whipUrl: string;
22
+ readonly token: string;
23
+ readonly stream: MediaStream;
24
+ /** Most bits per second for the picture; the browser sends less on a weak connection. */
25
+ readonly maxVideoBitrate: number;
26
+ /**
27
+ * What gives when the connection or the computer cannot keep up: the browser's choice
28
+ * (absent), or `maintain-resolution` -- fewer frames, never a smaller picture. A room's
29
+ * show keeps its size: it is passed through as it is, and a size changing mid-live reaches
30
+ * platforms and recordings as it is (spike 22: it started at 640x360 and grew).
31
+ */
32
+ readonly degradation?: RTCDegradationPreference;
33
+ /** TURN the owner configured, for networks that block UDP (spike 25). */
34
+ readonly iceServers?: readonly RTCIceServer[];
35
+ onState(state: WhipState): void;
36
+ }
37
+ /**
38
+ * H.264 first. Platforms take it as it is, so the server copies the picture and only
39
+ * converts the sound (spike 12); VP8 would have to be re-encoded, at a whole core's cost.
40
+ */
41
+ export declare function preferH264<T extends {
42
+ readonly mimeType: string;
43
+ }>(codecs: readonly T[]): T[];
44
+ /** What a refused offer means, in words a creator can act on. */
45
+ export declare function whipProblem(status: number): string;
46
+ /** The session's own address, from the answer's Location header (often relative). */
47
+ export declare function sessionUrl(location: string | null, whipUrl: string): string | undefined;
48
+ /** Wait for the browser to list its addresses, briefly: an offer without them can't connect. */
49
+ export declare function gathered(pc: RTCPeerConnection, maxMs: number): Promise<void>;
50
+ export declare function startWhip(options: WhipOptions): Promise<WhipSession>;
51
+ //# sourceMappingURL=whip.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"whip.d.ts","sourceRoot":"","sources":["../src/whip.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,MAAM,SAAS,GAAG,YAAY,GAAG,MAAM,GAAG,cAAc,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEpF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,4CAA4C;IAC5C,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,0FAA0F;IAC1F,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,yFAAyF;IACzF,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,wBAAwB,CAAC;IAChD,yEAAyE;IACzE,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IAC9C,OAAO,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,CAAC;CACjC;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS;IAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,GAAG,CAAC,EAAE,CAG7F;AAED,iEAAiE;AACjE,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAWlD;AAED,qFAAqF;AACrF,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAOvF;AAED,gGAAgG;AAChG,wBAAgB,QAAQ,CAAC,EAAE,EAAE,iBAAiB,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAa5E;AAED,wBAAsB,SAAS,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CA6F1E"}
package/package.json CHANGED
@@ -1,6 +1,33 @@
1
1
  {
2
2
  "name": "@creekx/web",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.1.0",
4
+ "description": "Play and publish creekX live streams on any web page: WebRTC with HLS behind it.",
5
+ "license": "Apache-2.0",
6
+ "type": "module",
7
+ "exports": {
8
+ ".": {
9
+ "types": "./dist/index.d.ts",
10
+ "import": "./dist/creekx-web.js"
11
+ }
12
+ },
13
+ "dependencies": {
14
+ "hls.js": "^1.7.3"
15
+ },
16
+ "devDependencies": {
17
+ "typescript": "^5.7.2",
18
+ "vite": "^6.4.3",
19
+ "vitest": "^3.2.6"
20
+ },
21
+ "files": [
22
+ "dist",
23
+ "NOTICE"
24
+ ],
25
+ "publishConfig": {
26
+ "access": "public"
27
+ },
28
+ "scripts": {
29
+ "typecheck": "tsc -p tsconfig.json --noEmit",
30
+ "test": "vitest run",
31
+ "build": "vite build && tsc -p tsconfig.build.json"
32
+ }
6
33
  }
package/README.md DELETED
@@ -1,3 +0,0 @@
1
- # Temporary Holding Version
2
-
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.