synxed-sdk 0.2.4 → 0.2.6

package/README.md

@@ -1,198 +1,181 @@
 # Synxed SDK
 
-The official Synxed SDK for frontend developers to integrate high-quality music streaming into their applications.
+Add Synxed music to your website or app in a few minutes — playlists, live radio, voice commands, and a ready-made player UI.
 
 [![npm version](https://img.shields.io/npm/v/synxed-sdk.svg)](https://www.npmjs.com/package/synxed-sdk)
-[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
 
-## Features
+## What you need
 
-- **Simple integration**: Play songs, playlists, or **24/7 live radio** with a few lines of code.
-- **High-fidelity streaming**: Robust HLS support via `hls.js` for seamless playback across browsers (on-demand content).
-- **Built-in analytics**: Session `stream_start` plus automatic **`heartbeat`** intervals from the server `initAck` (including radio, which uses `positionMs: 0`).
-- **Framework-agnostic core**: `SynxedPlayer` works in React, Vue, Angular, or vanilla JS.
-- **Optional web UI**: Vanilla DOM overlay (`SynxedWebPlayer`) with **mini**, **wide**, and **large** layouts — works in any framework; **theme** and **placement** are fully configurable.
-- **Type-safe**: Written in TypeScript with full definitions.
+1. A **Synxed API key** (from your Synxed developer account `https://portal.synxed.com`).
+2. Your **API URL** (Our api url: `https://api.synxed.com`).
+3. A **playlist code**, **Single Song** or choose **live radio**.
 
-## Installation
+## Install
 
 ```bash
 npm install synxed-sdk
 ```
 
-> **Note**: For HLS streaming support in browsers like Chrome, Firefox, and Edge, please ensure `hls.js` is installed in your project.
+## Easiest setup — built-in player
 
-```bash
-npm install hls.js
-```
+This adds a floating music bar to your page. No React or special framework required.
 
-## Quick Start
+### Play a playlist
 
-### Initialize the player
+```html
+<script type="module">
+  import { SynxedWebPlayer } from "synxed-sdk";
 
-```typescript
-import { SynxedPlayer } from "synxed-sdk";
+  SynxedWebPlayer.mount({
+    apiKey: "YOUR_SYNXED_API_KEY",
+    serverUrl: "https://api.synxed.com",
+    source: { type: "playlist", playlistCode: "sxpl_YOUR_CODE" },
+  });
+</script>
+```
 
-const player = new SynxedPlayer({
+### Play live radio
+
+```javascript
+SynxedWebPlayer.mount({
   apiKey: "YOUR_SYNXED_API_KEY",
   serverUrl: "https://api.synxed.com",
-  autoConnect: true,
+  source: { type: "radio" },
 });
 ```
 
-### Play a playlist
+### Put the player inside your own box
 
-```typescript
-player.playPlaylist({
-  playlistCode: "sxpl_VZCCGQAQJV",
+```javascript
+SynxedWebPlayer.mount({
+  container: document.getElementById("my-player"),
+  apiKey: "YOUR_SYNXED_API_KEY",
+  serverUrl: "https://api.synxed.com",
+  source: { type: "playlist", playlistCode: "sxpl_YOUR_CODE" },
 });
 ```
 
-### Play a single song
+## Player sizes
 
-```typescript
-player.playSong({
-  catalogTrackId: "2dcad8e0-3695-4971-9e35-f762f3f9d3a5",
-});
+| Mode    | What it looks like              |
+| ------- | ------------------------------- |
+| `wide`  | Bar across the bottom (default) |
+| `mini`  | Small round DJ button           |
+| `large` | Bigger card with visualizer     |
 
-player.playSong({
-  internalTrackId: "track-uuid-here",
+```javascript
+SynxedWebPlayer.mount({
+  apiKey: "...",
+  serverUrl: "...",
+  source: { type: "playlist", playlistCode: "sxpl_..." },
+  mode: "mini",
 });
 ```
 
-### Live radio
-
-Continuous **non-HLS** stream (not seekable). The SDK sends `CONTENT_KIND_RADIO` (`4`) over the same native `/sdk` WebSocket; the server returns a direct `playbackUrl` (e.g. MPEG stream).
-
-```typescript
-await player.playRadio({ listenerId: "optional-stable-id" });
-```
-
-- **`skip` / `previous` / `skipTo` / `seek`**: no-ops for radio (the live edge keeps moving on the server).
-- **`pause` / `resume`**: local audio only; when the user resumes, they rejoin the live stream.
-- **Metadata**: poll the REST endpoint (unauthenticated on most deployments):
+## Move the player on screen
 
-```typescript
-import { fetchRadioNowPlaying } from "synxed-sdk";
-
-const np = await fetchRadioNowPlaying("https://api.synxed.com");
-// { title, station?, isLive? } — poll every 10–15s for “now playing” UI
-```
-
-### Optional web player UI (vanilla — no React required)
-
-```typescript
-import { SynxedWebPlayer } from "synxed-sdk";
-
-const ui = SynxedWebPlayer.mount({
-  apiKey: "YOUR_SYNXED_API_KEY",
-  serverUrl: "https://api.synxed.com",
+```javascript
+SynxedWebPlayer.mount({
+  apiKey: "...",
+  serverUrl: "...",
   source: { type: "radio" },
-  mode: "wide",
-  attribution: "DJ Jesse · Synxed × Your Brand",
-  theme: {
-    accent: "#ef4444",
-    glow: "rgba(239, 68, 68, 0.35)",
-    background: "#0a0707",
-  },
   position: { placement: "top-left", offsetX: 16, offsetY: 16 },
   draggable: true,
 });
-
-// Later: ui.destroy();
 ```
 
-Mount into your own container instead of a fixed overlay:
+## Match your brand colors
 
-```typescript
+```javascript
 SynxedWebPlayer.mount({
-  container: document.getElementById("player-slot")!,
   apiKey: "...",
   serverUrl: "...",
   source: { type: "playlist", playlistCode: "sxpl_..." },
+  theme: {
+    accent: "#22c55e",
+    background: "#0a0a0a",
+    glow: "rgba(34, 197, 94, 0.35)",
+  },
 });
 ```
 
-**Modes**: `mini` (avatar only), `wide` (pill bar, default), `large` (card + visualizer). Skip controls are hidden for radio.
-**Draggable**: Set `draggable: true` (default is `false`) to allow users to move the floating player around the screen so it doesn't obstruct their view.
+## Talk to the DJ (voice playlists)
+
+**Hold** the Synxed DJ avatar (the spinning circle) and say what you want to hear — for example _“play upbeat workout songs”_.
 
-In React/Vue, create the player in `useEffect` / `onMounted` and call `destroy()` on teardown — same class, no separate React package.
+- **Tap** the DJ → play or pause the music.
+- **Hold** the DJ → speak your request; release when done (or stop talking and it sends automatically).
+- While you speak, the DJ icon switches to the AI listening view.
+- Music pauses while you talk and can resume when you tap again.
 
-### Playback controls
+To turn voice off:
 
-```typescript
-player.pause();
-player.resume();
-player.stop();
-player.seek(30000); // on-demand only; no-op for radio
-player.setVolume(0.8);
-player.skip();
-player.previous();
-player.skipTo(2);
+```javascript
+SynxedWebPlayer.mount({
+  enableVoice: false,
+  // ...other options
+});
 ```
 
-## Listening for events
+## Skip button and ads
 
-```typescript
-player.on("stateChange", (state) => {
-  console.log("Player status:", state.status);
-});
+- During normal playback, the **skip** button jumps to the next song.
+- During an ad, the same button shows a **short countdown** (about 5 seconds), then you can skip the ad.
+- After the ad, the skip button works again for the next song.
 
-player.on("timeUpdate", ({ currentTime, duration }) => {
-  const progress = (currentTime / duration) * 100;
-  console.log(`Progress: ${progress.toFixed(2)}%`);
-});
+## Build your own UI (optional)
 
-player.on("error", (err) => {
-  console.error("Playback Error:", err.message);
-});
-```
+If you want full control over buttons and layout, use `SynxedPlayer` instead of `SynxedWebPlayer`:
 
-## API reference
+```javascript
+import { SynxedPlayer } from "synxed-sdk";
 
-### `new SynxedPlayer(config)`
+const player = new SynxedPlayer({
+  apiKey: "YOUR_SYNXED_API_KEY",
+  serverUrl: "https://api.synxed.com",
+  autoConnect: true,
+});
 
-- `apiKey`: `string` (required)
-- `serverUrl`: `string` (required)
-- `autoConnect`: `boolean` (default `true`)
+await player.playPlaylist({ playlistCode: "sxpl_YOUR_CODE" });
 
-### Methods
+document.getElementById("play").onclick = () => player.resume();
+document.getElementById("pause").onclick = () => player.pause();
+document.getElementById("skip").onclick = () => player.skip();
+```
 
-- `playSong(options)`: `Promise<void>`
-- `playPlaylist(options)`: `Promise<void>`
-- `playRadio(options?)`: `Promise<void>` — live radio (`listenerId` optional)
-- `pause()` / `resume()` / `stop()`
-- `skip()` / `previous()` / `skipTo(index)` — playlist / on-demand only
-- `seek(ms)` — on-demand only (no-op for radio)
-- `setVolume(0–1)`
-- `destroy()`
+### Voice with your own buttons
 
-### Getters
+```javascript
+const dj = document.getElementById("dj-avatar");
 
-- `currentTrack`: current `TrackInfo | null`
-- `contentKind`: last `play*` kind (`ContentKind` enum, including `RADIO`)
+dj.addEventListener("pointerdown", () => player.beginVoiceHold());
+dj.addEventListener("pointerup", () => player.endVoiceHold());
+```
 
-### `fetchRadioNowPlaying(serverUrl, init?)`
+## Clean up when leaving the page
 
-`Promise<RadioNowPlaying | null>` — wraps `GET {serverUrl}/radio/now-playing`.
+```javascript
+const ui = SynxedWebPlayer.mount({
+  /* ... */
+});
 
-### Events
+// When your app unmounts or navigates away:
+ui.destroy();
+```
 
-- `stateChange`, `timeUpdate`, `trackChange`, `queueUpdated`, `error`, `connected`, `disconnected`
+## Radio “now playing” title
 
-### `TrackInfo`
+For radio, you can show the current song name on your own label:
 
-```typescript
-interface TrackInfo {
-  id: string;
-  kind: "catalog" | "internal";
-  title?: string;
-  artist?: string;
-  duration?: number;
-  albumArt?: string;
-}
+```javascript
+import { fetchRadioNowPlaying } from "synxed-sdk";
+
+const info = await fetchRadioNowPlaying("https://api.synxed.com");
+if (info) console.log(info.title);
 ```
 
+Poll every 10–15 seconds to keep the title fresh.
+
 ## License
 
 Copyright © [Synxed.com](https://synxed.com)

package/dist/index.d.mts

@@ -155,6 +155,7 @@ declare class SynxedPlayer extends EventEmitter<SynxedEvents> {
     private voiceListenerId;
     private pendingPlaybackLoad;
     private voiceAutoEndOnSilence;
+    private pausedForVoice;
     constructor(config: SynxedConfig);
     get currentTrack(): TrackInfo | null;
     /** Active playback init kind from the last `play*` call (RADIO, PLAYLIST, SONG, …). */
@@ -185,6 +186,12 @@ declare class SynxedPlayer extends EventEmitter<SynxedEvents> {
     endVoiceHold(): Promise<void>;
     /** Cancel an in-progress voice hold without sending audio to the server. */
     cancelVoiceHold(): void;
+    /**
+     * Close the voice UI: cancel recording if active and resume playback if it was
+     * paused for voice.
+     */
+    dismissVoiceAndResume(): void;
+    get isVoiceUiActive(): boolean;
     pause(): void;
     resume(): void;
     stop(): void;
@@ -337,8 +344,6 @@ interface SynxedWebPlayerOptions {
     mode?: SynxedWebPlayerMode;
     theme?: SynxedWebPlayerTheme;
     position?: SynxedWebPlayerPosition;
-    avatarUrl?: string;
-    voiceAvatarUrl?: string;
     attribution?: string;
     nowPlayingPollMs?: number;
     powerByLabel?: string;
@@ -347,8 +352,10 @@ interface SynxedWebPlayerOptions {
     style?: Partial<CSSStyleDeclaration>;
     onMiniClick?: () => void;
     draggable?: boolean;
-    /** Press-and-hold DJ avatar for voice commands. Set `false` to disable. Default `true`. */
+    /** Press-and-hold DJ avatar for voice. Set `false` to disable. Default `true`. */
     enableVoice?: boolean;
+    /** Ms to hold before voice starts (prevents opening AI on quick tap). Default `450`. */
+    voiceHoldMs?: number;
     listenerId?: string;
 }
 
@@ -380,6 +387,12 @@ declare class SynxedWebPlayer {
     private avatarVoiceHolding;
     private suppressMiniClick;
     private voiceAvatarPreview;
+    private voiceHoldActivated;
+    private voiceUiDismissed;
+    private voiceHoldTimer;
+    private readonly defaultVoiceHoldMs;
+    /** Avatar to restore after an ad (DJ / album art — not ad or voice AI). */
+    private avatarImageBeforeAd;
     constructor(options: SynxedWebPlayerOptions);
     /** Convenience factory — same as `new SynxedWebPlayer(options)`. */
     static mount(options: SynxedWebPlayerOptions): SynxedWebPlayer;
@@ -404,14 +417,21 @@ declare class SynxedWebPlayer {
     private initEngine;
     /** Press-and-hold DJ avatar to stream voice; release or silence auto-ends capture. */
     private wireAvatarVoiceHold;
+    private isVoiceUiOpen;
+    private dismissVoiceUi;
+    private resetVoiceHoldState;
     private applyVoiceVisual;
     private isVoiceAvatarActive;
+    private getContentAvatarUrl;
     private getAvatarImageUrl;
     private refreshAvatarImage;
     private startNowPlayingPoll;
     private stopNowPlayingPoll;
     private handleSkipClick;
-    /** YouTube-style ad skip pill: "Ad · 5" countdown → "Skip Ad". */
+    /**
+     * During ads: swap skip icon for countdown text in the same control (no style changes).
+     * After ads: restore skip icon for the next track.
+     */
     private applyAdSkipUi;
     private restoreTrackSkipButton;
     private displayLine;

package/dist/index.d.ts

@@ -155,6 +155,7 @@ declare class SynxedPlayer extends EventEmitter<SynxedEvents> {
     private voiceListenerId;
     private pendingPlaybackLoad;
     private voiceAutoEndOnSilence;
+    private pausedForVoice;
     constructor(config: SynxedConfig);
     get currentTrack(): TrackInfo | null;
     /** Active playback init kind from the last `play*` call (RADIO, PLAYLIST, SONG, …). */
@@ -185,6 +186,12 @@ declare class SynxedPlayer extends EventEmitter<SynxedEvents> {
     endVoiceHold(): Promise<void>;
     /** Cancel an in-progress voice hold without sending audio to the server. */
     cancelVoiceHold(): void;
+    /**
+     * Close the voice UI: cancel recording if active and resume playback if it was
+     * paused for voice.
+     */
+    dismissVoiceAndResume(): void;
+    get isVoiceUiActive(): boolean;
     pause(): void;
     resume(): void;
     stop(): void;
@@ -337,8 +344,6 @@ interface SynxedWebPlayerOptions {
     mode?: SynxedWebPlayerMode;
     theme?: SynxedWebPlayerTheme;
     position?: SynxedWebPlayerPosition;
-    avatarUrl?: string;
-    voiceAvatarUrl?: string;
     attribution?: string;
     nowPlayingPollMs?: number;
     powerByLabel?: string;
@@ -347,8 +352,10 @@ interface SynxedWebPlayerOptions {
     style?: Partial<CSSStyleDeclaration>;
     onMiniClick?: () => void;
     draggable?: boolean;
-    /** Press-and-hold DJ avatar for voice commands. Set `false` to disable. Default `true`. */
+    /** Press-and-hold DJ avatar for voice. Set `false` to disable. Default `true`. */
     enableVoice?: boolean;
+    /** Ms to hold before voice starts (prevents opening AI on quick tap). Default `450`. */
+    voiceHoldMs?: number;
     listenerId?: string;
 }
 
@@ -380,6 +387,12 @@ declare class SynxedWebPlayer {
     private avatarVoiceHolding;
     private suppressMiniClick;
     private voiceAvatarPreview;
+    private voiceHoldActivated;
+    private voiceUiDismissed;
+    private voiceHoldTimer;
+    private readonly defaultVoiceHoldMs;
+    /** Avatar to restore after an ad (DJ / album art — not ad or voice AI). */
+    private avatarImageBeforeAd;
     constructor(options: SynxedWebPlayerOptions);
     /** Convenience factory — same as `new SynxedWebPlayer(options)`. */
     static mount(options: SynxedWebPlayerOptions): SynxedWebPlayer;
@@ -404,14 +417,21 @@ declare class SynxedWebPlayer {
     private initEngine;
     /** Press-and-hold DJ avatar to stream voice; release or silence auto-ends capture. */
     private wireAvatarVoiceHold;
+    private isVoiceUiOpen;
+    private dismissVoiceUi;
+    private resetVoiceHoldState;
     private applyVoiceVisual;
     private isVoiceAvatarActive;
+    private getContentAvatarUrl;
     private getAvatarImageUrl;
     private refreshAvatarImage;
     private startNowPlayingPoll;
     private stopNowPlayingPoll;
     private handleSkipClick;
-    /** YouTube-style ad skip pill: "Ad · 5" countdown → "Skip Ad". */
+    /**
+     * During ads: swap skip icon for countdown text in the same control (no style changes).
+     * After ads: restore skip icon for the next track.
+     */
     private applyAdSkipUi;
     private restoreTrackSkipButton;
     private displayLine;