{"_id":"@bilbomusic/player-plugin-sdk","_rev":"3-7215b23095915752f397238bde77dcdc","name":"@bilbomusic/player-plugin-sdk","dist-tags":{"latest":"1.0.2"},"versions":{"1.0.0":{"name":"@bilbomusic/player-plugin-sdk","version":"1.0.0","keywords":["bilbomusic","player","sdk","plugin","visualizer","iframe","audio","postmessage"],"author":{"name":"Bilbo Music"},"license":"MIT","_id":"@bilbomusic/player-plugin-sdk@1.0.0","maintainers":[{"name":"tyufyakin","email":"tiufyakin@gmail.com"}],"homepage":"https://bilbomusic.com","bugs":{"url":"https://github.com"},"dist":{"shasum":"d19ea29aae21d4fa16ee3c79e7aaa29bd529a87b","tarball":"https://registry.npmjs.org/@bilbomusic/player-plugin-sdk/-/player-plugin-sdk-1.0.0.tgz","fileCount":4,"integrity":"sha512-STv+L4EAocVBdaDPeOkuy0llLieg8ax9WGMbLZ7zVaEraYyFb9nXaBvQvgE00V4FvmLU5awM8o1zwnUcwrmKSw==","signatures":[{"sig":"MEQCICT+6H7/8YDQCSBanBnjugJgNxLaA9BVjlyswR0G+7TDAiAQXID1i2zJuvIn3WBmDW/0VQ2eFH/yxLdLLsH7Jy2/lw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":28121},"main":"./index.js","type":"module","exports":{".":{"import":"./index.js","default":"./index.js"}},"gitHead":"cee593c02a4f7252b44f94b24a80d2d2f98b81aa","scripts":{"test":"echo \"Error: no test specified\" && exit 0"},"_npmUser":{"name":"tyufyakin","email":"tiufyakin@gmail.com"},"repository":{"url":"git+https://github.com","type":"git"},"_npmVersion":"10.9.3","description":"Official JavaScript SDK for creating custom player skins, visual themes, and interactive visualizer extensions within the Bilbo Music platform ecosystem.","directories":{},"_nodeVersion":"22.20.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/player-plugin-sdk_1.0.0_1782990206543_0.48305839596215083","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@bilbomusic/player-plugin-sdk","version":"1.0.1","keywords":["bilbomusic","player","sdk","plugin","visualizer","iframe","audio","postmessage"],"author":{"name":"Bilbo Music"},"license":"MIT","_id":"@bilbomusic/player-plugin-sdk@1.0.1","maintainers":[{"name":"tyufyakin","email":"tiufyakin@gmail.com"}],"homepage":"https://bilbomusic.com","bugs":{"url":"https://github.com/Bilbo-Music/player-plugin-sdk/issues"},"dist":{"shasum":"9d9f18c44ed84aa700e13dbb7f272a711e193cb0","tarball":"https://registry.npmjs.org/@bilbomusic/player-plugin-sdk/-/player-plugin-sdk-1.0.1.tgz","fileCount":4,"integrity":"sha512-OhbdiFA+47SJbZbHGY2tR8T1i9/WCl0DMKuzIB9MDtNtSH4Zbk76Izjt6kANBmtVEXsxS2fjzoyu3SFOclEYTA==","signatures":[{"sig":"MEUCIGSvq8nrlmhNMOYUGpII1D6THQXlwl2OK2LYiN+i4Jl9AiEAki0u1sX2rRQy1k5OfISiYPLnUXpINhb1fCdTvIziP8Q=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":32609},"main":"./index.js","type":"module","exports":{".":{"import":"./index.js","default":"./index.js"}},"gitHead":"7e4b8a3884d370aa4496c79bf031812a0e81c5fe","scripts":{"test":"echo \"Error: no test specified\" && exit 0"},"_npmUser":{"name":"tyufyakin","email":"tiufyakin@gmail.com"},"repository":{"url":"git+https://github.com/Bilbo-Music/player-plugin-sdk.git","type":"git"},"_npmVersion":"10.9.3","description":"Official JavaScript SDK for creating custom player skins, visual themes, and interactive visualizer extensions within the Bilbo Music platform ecosystem.","directories":{},"_nodeVersion":"22.20.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/player-plugin-sdk_1.0.1_1784104278636_0.5951895293893439","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@bilbomusic/player-plugin-sdk","version":"1.0.2","description":"Official JavaScript SDK for creating custom player skins, visual themes, and interactive visualizer extensions within the Bilbo Music platform ecosystem.","type":"module","main":"./index.js","exports":{".":{"import":"./index.js","default":"./index.js"}},"scripts":{"test":"echo \"Error: no test specified\" && exit 0"},"repository":{"type":"git","url":"git+https://github.com/Bilbo-Music/player-plugin-sdk.git"},"keywords":["bilbomusic","player","sdk","plugin","visualizer","iframe","audio","postmessage"],"author":{"name":"Bilbo Music"},"license":"MIT","bugs":{"url":"https://github.com/Bilbo-Music/player-plugin-sdk/issues"},"homepage":"https://bilbomusic.com","publishConfig":{"access":"public"},"_id":"@bilbomusic/player-plugin-sdk@1.0.2","gitHead":"3962bac6a20c76214042a2c4baf6261b8494e6b9","_nodeVersion":"22.20.0","_npmVersion":"10.9.3","dist":{"integrity":"sha512-L1vBqcevn6ftXWR79CUInanDu3GSpW1HeKMvMHtUizoLzNdn5oGtJSf3cJZqWh1kxEeyrXb+s+W1wUVatp+PTA==","shasum":"b3d1d9914057bdae93cfc169b2e08e48c7702536","tarball":"https://registry.npmjs.org/@bilbomusic/player-plugin-sdk/-/player-plugin-sdk-1.0.2.tgz","fileCount":4,"unpackedSize":33040,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIAkbXcoQHNp+TM3olbiSP+blqZAV+3bVI8XT0Z3Y0qfdAiAvawPoLX85ywWyPFK0QcAc7gDNG4vwW59wDlX4Cw2hDA=="}]},"_npmUser":{"name":"tyufyakin","email":"tiufyakin@gmail.com"},"directories":{},"maintainers":[{"name":"tyufyakin","email":"tiufyakin@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/player-plugin-sdk_1.0.2_1784828782963_0.022689596958679337"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-02T11:03:26.409Z","modified":"2026-07-23T17:46:23.258Z","1.0.0":"2026-07-02T11:03:26.692Z","1.0.1":"2026-07-15T08:31:18.777Z","1.0.2":"2026-07-23T17:46:23.089Z"},"bugs":{"url":"https://github.com/Bilbo-Music/player-plugin-sdk/issues"},"author":{"name":"Bilbo Music"},"license":"MIT","homepage":"https://bilbomusic.com","keywords":["bilbomusic","player","sdk","plugin","visualizer","iframe","audio","postmessage"],"repository":{"type":"git","url":"git+https://github.com/Bilbo-Music/player-plugin-sdk.git"},"description":"Official JavaScript SDK for creating custom player skins, visual themes, and interactive visualizer extensions within the Bilbo Music platform ecosystem.","maintainers":[{"name":"tyufyakin","email":"tiufyakin@gmail.com"}],"readme":"# `@bilbomusic/player-plugin-sdk`\r\n\r\nThe official JavaScript SDK for creating custom player skins, visual themes, and interactive visualizer extensions within the [Bilbo Music](https://bilbomusic.com) music platform ecosystem.\r\n\r\nThis library handles secure, isolated, and high-performance cross-origin data synchronization between the main Bilbo Music host player application and your custom plugin running inside a sandboxed `<iframe>`. It abstracts low-level `postMessage` exchanges into a developer-friendly, event-driven API for managing audio state, tracking playlist queues, and rendering real-time frequency data.\r\n\r\n---\r\n\r\n## 📦 Installation\r\n\r\nInstall the package into your custom player plugin project repository via any JavaScript node package manager:\r\n\r\n```bash\r\nnpm install @bilbomusic/player-plugin-sdk\r\n# or\r\nyarn add @bilbomusic/player-plugin-sdk\r\n# or\r\npnpm add @bilbomusic/player-plugin-sdk\r\n```\r\n\r\n---\r\n\r\n## 🚀 Quick Start\r\n\r\nImport the `playerSdk` singleton module directly into your bundle. The library instantly invokes an automated handshake layer signaling connectivity back to the **Bilbo Music** application core.\r\n\r\n```javascript\r\nimport { playerSdk } from '@bilbomusic/player-plugin-sdk';\r\n\r\n// 1. Declaratively hide native player UI nodes to map out your layout\r\nplayerSdk.setUiConfig({\r\n    carousel: false,    // Hide the host's cover art viewer to draw a custom one\r\n    progressBar: false, // Disable the host trackbar to use an interactive Waveform tracker\r\n    interactive: true   // Authorize pointer events on the iframe so our buttons work\r\n});\r\n\r\n// 2. Attach a generalized reactive observer tracking screen mutation parameters\r\nplayerSdk.on('change', ({ type, payload }) => {\r\n    if (type === 'track') {\r\n        console.log('Now playing:', payload.track.title);\r\n        document.getElementById('track-title').innerText = payload.track.title;\r\n    }\r\n    if (type === 'position') {\r\n        console.log('Current playback milestone (ms):', payload.position);\r\n    }\r\n}, 'default');\r\n\r\n// 3. Delegate actions seamlessly back to the hardware device audio pipeline\r\ndocument.getElementById('playBtn').addEventListener('click', () => {\r\n    playerSdk.play();\r\n});\r\n```\r\n---\r\n\r\n## 🎨 Declarative UI Configuration (`setUiConfig`)\r\n\r\nThe `playerSdk.setUiConfig(config)` method accepts a structural `Object` allowing your plugin to control the layout and visibility of native player blocks surrounding your iframe within the parent shell.\r\n\r\n### Configuration Schema Reference\r\n```javascript\r\nplayerSdk.setUiConfig({\r\n    carousel: true,       // Show/hide the interactive track cover image carousel\r\n    interactive: false,   // Set to true to allow pointer clicks/drags to pass into the iframe.\r\n                          // If false, the iframe ignores click events (allowing clicks to pass through to the host).\r\n    trackInfo: true,      // Show/hide the block containing track title, artist name, and the context menu kebab button\r\n    progressBar: true,    // Show/hide the native timeline scrub / progress slider\r\n    controls: {           // Individual playback button controls\r\n        like: true,       // Show/hide the Favorite (Heart) button\r\n        dislike: true,    // Show/hide the Dislike button\r\n        playPause: true,  // Show/hide the central Play/Pause toggle\r\n        next: true,       // Show/hide the Skip Next button\r\n        prev: true        // Show/hide the Skip Previous button\r\n    },\r\n    actions: {            // Utility action layout buttons\r\n        repeat: true,     // Show/hide the track/queue loop/repeat toggle button\r\n        playlist: true    // Show/hide the playlist/queue drawer toggle button\r\n    },\r\n    minimize: true        // Show/hide the main header close/minimize chevron button\r\n});\r\n```\r\n\r\n---\r\n\r\n## 🔌 Host Handshake & Initialization State (`PLAYER_INIT`)\r\n\r\nWhen your plugin iframe is fully loaded, the parent host sends a `PLAYER_INIT` message containing the complete, pre-hydrated configuration of the host state, current playback progress, custom device safe-area styling tokens, and the user identity.\r\n\r\n### Complete Initialization Payload Structure\r\n\r\nThe object received as the payload in the `init` event (or accessible via `playerSdk.state` after startup) conforms to this design:\r\n\r\n```typescript\r\ninterface PlayerInitPayload {\r\n    // 🌐 Locale and Regional settings\r\n    locale: {\r\n        locale: string;      // Current UI locale language code (e.g., \"ru\", \"en\")\r\n        rtl: boolean;        // Right-to-Left formatting indicator\r\n    };\r\n    \r\n    // 🎨 Visual & Experience Preferences\r\n    theme: 'light' | 'dark'; // Active application skin preference\r\n    vibration: boolean;      // Haptic/vibration feedback toggled on or off by the user\r\n    \r\n    // 📱 Parent Frame Layout State\r\n    player: {\r\n        expanded: boolean;   // Whether the player is currently opened full-screen\r\n    };\r\n    \r\n    // 📑 Virtual Workspace Panes (Default layout views)\r\n    panes: {\r\n        [paneId: string]: {\r\n            track: TrackPreview | null;     // Active playing track metadata\r\n            queue: QueuePreview | null;     // Active queue track listings\r\n            position: number;               // Current playback time tracker in milliseconds\r\n            state: 'playing' | 'paused' | 'stopped'; // Active media playback state\r\n            prevDisabled: boolean;          // Previous skip button eligibility status\r\n            nextDisabled: boolean;          // Next skip button eligibility status\r\n            hasQueue: boolean;              // Tracks presence inside the play queue\r\n            repeat: 'none' | 'queue' | 'track'; // Loop playback configurations\r\n            reaction: 'LIKE' | 'DISLIKE' | null; // Preference interaction state\r\n        }\r\n    };\r\n    \r\n    // 📐 Host Custom Environment Styling Tokens\r\n    styles: {\r\n        '--max-safe-area-inset-top': string;\r\n        '--tg-safe-area-inset-top': string;\r\n        '--max-content-safe-area-inset-top': string;\r\n        '--tg-content-safe-area-inset-top': string;\r\n    };\r\n    \r\n    // 👤 Anonymized Current User Profile\r\n    user: {\r\n        id: string | null;   // Pseudonymized, safe user identification hash\r\n    };\r\n}\r\n```\r\n\r\n---\r\n\r\n## 📑 Event Bus Specification\r\n\r\nRegister and tear down hook listeners using `.on(event, callback, pane)` and `.off(event, callback, pane)` handlers.\r\n\r\n### Global System Events\r\nThese hooks run continuously outside the boundaries of contextual pane view layouts:\r\n*   `init`: Fires exactly once upon bootstrap handshake termination. Transmits the absolute current root `state` configuration object.\r\n*   `theme`: Dispatched when the environment triggers systemic dark/light skin adjustments. Emits `{ theme: 'light' | 'dark' }`.\r\n*   `locale`: Dispatched when regional runtime changes occur. Returns a safe layout configuration schema: `{ locale: string, rtl: boolean }`.\r\n*   `player`: Signals changes regarding core display modes. Returns `{ expanded: boolean }`.\r\n\r\n### Scoped Pane Events\r\nBound exclusively to independent application UI screens (defaults to `pane = 'default'`).\r\n*   `change`: The primary atomic multi-property observer for theme developers. Fires when *any* variable modifies within the active viewport profile. Returns an argument matching the structure: `{ type: string, payload: any, pane: string }`.\r\n*   `audioFrame`: Stream gate dispatching digital signal audio frequency bands for spectrum analyzer canvases. Fires at up to ~60 frames per second. Yields a single `Uint8Array` binary mapping.\r\n*   You may also attach explicit hooks listening strictly to a specific variable name instead of checking the global aggregate tracker (e.g. subscribing directly to events named `'track'`, `'position'`, `'state'`, or `'queue'`).\r\n\r\n---\r\n\r\n## 🛠️ API Reference Methods\r\n\r\n### Playback Automation\r\n*   `playerSdk.play(pane)` — Resumes active media stream decoding.\r\n*   `playerSdk.pause(pane)` — Halts audio rendering at the current frame milestone.\r\n*   `playerSdk.seek(ms, pane)` — Sets playback runtime forward or backward to an explicit milestone in milliseconds (`ms` must be a valid `number`).\r\n*   `playerSdk.next(pane)` — Skips ahead to the next logical sequence block item.\r\n*   `playerSdk.prev(pane)` — Jumps back toward the preceding asset record.\r\n\r\n### Container Overlays & Layouts\r\n*   `playerSdk.expand()` — Prompts the parent viewport frame to transition into a full-height, expanded view configuration layer.\r\n*   `playerSdk.collapse()` — Minimizes the parent frame bounds into a compact mini-player bar profile layout.\r\n*   `playerSdk.openTrackKebab()` — Triggers the opening of the native contextual tracks feature card/modal dialog overview.\r\n*   `playerSdk.openPlaylist()` — Displays the global slide-out queue overlay screen list container.\r\n*   `playerSdk.setUiConfig(config)` — Accepts a structural config `Object` modifying the visibility state flags of parent core blocks surrounding the plugin node wrapper.\r\n\r\n### Queue & Metadata Modifications\r\n*   `playerSdk.playQueueIndex(index, pane)` — Instructs the streaming backend to break current execution order and mount the sequential entity track matching the specified zero-based array position value (`index`).\r\n*   `playerSdk.reaction(reaction, pane)` — Passes user preference validation indicators directly to backend endpoints (`'LIKE'`, `'DISLIKE'`, `null`, or `''`).\r\n*   `playerSdk.repeat(repeat, pane)` — Modifies active collection repeat modes (`'none'`, `'queue'`, `'track'`).\r\n\r\n---\r\n\r\n## 📊 Data Formats & DTO (Data Transfer Objects)\r\n\r\nThe following type definitions document the incoming payloads dispatched down from the Bilbo Music environment into the player plugin runtime.\r\n\r\n### `Image`\r\nA comprehensive asset record managing pre-rendered variant dimensions to enforce optimized RAM consumption inside the client web wrapper.\r\n*   `crop`: `string` — Uniform cropped thumbnail endpoint mapping exactly to **180x180** dimensions. Recommended for timeline history line items, list indices, and side queues.\r\n*   `resized`: `string` — High-definition compressed variant mapping to **1000x1000** properties. Best suited for focal backgrounds and center cover art cards.\r\n*   `original`: `string` — Full-resolution fallback referencing the uncompressed source matrix asset directly.\r\n\r\n### `ArtistPreview`\r\n*   `id`: `string | number` — The unique database or platform identifier for the artist.\r\n*   `name`: `string` — Public identity string or stage name representing the performer profile.\r\n*   `code`: `string` — Systemic alphanumeric slug mapping the performer uniquely inside route configurations.\r\n*   `profileImage`: `Image` — Multi-tier image record referencing portrait asset arrays.\r\n\r\n### `TrackPreview`\r\n*   `id`: `string | number` — The unique database or platform identifier for the track.\r\n*   `title`: `string` — The primary presentation name string of the track.\r\n*   `artists`: `string` — Pre-formatted utility string concatenating multiple composer identities into a readable line.\r\n*   `duration`: `number` — Total playback length value evaluated exclusively in **milliseconds**.\r\n*   `bpm`: `number | null` — Measured speed metrics tracking structural beats per minute.\r\n*   `wave`: `number[]` — Array containing **exactly 100 integer positions** mapping static track sound amplitude volumes. Theoretical density calculations span from `0` up to `1000`, though real-world production track master peaks safely average within the `500–700` threshold limits. Useful for drawing custom audio waveforms that act as full-length interactive scrubbars.\r\n*   `isExplicit`: `boolean` — Content indicator denoting whether structural components feature restricted lyrical content.\r\n*   `version`: `string | null` — Supplemental performance label strings (e.g. `\"Remix\"`, `\"Radio Edit\"`, `\"Acoustic Mix\"`).\r\n*   `fromProject`: `boolean` — System tag validating native Bilbo-exclusive resource distribution tracks.\r\n*   `cover`: `Image` — Multi-scale picture payload referencing track artwork maps.\r\n*   `contributors`: `Object` — Granular profile map tracking credits:\r\n    *   `primary`: `ArtistPreview[]` — Core headline performer entities.\r\n    *   `featured`: `ArtistPreview[]` — Guest performers contributing to the specific composition.\r\n\r\n### `ReleasePreview`\r\n*   `id`: `string | number` — The unique database or platform identifier for the release (album, single, or EP).\r\n*   `title`: `string` — Legal name tracking collective works (Albums, Box sets, Compilation EPs).\r\n*   `cover`: `Image` — Graphic reference catalog mapping release compilation packaging artwork.\r\n*   `fromProject`: `boolean` — Identifies compilation packages associated with internal project tags.\r\n*   `artists`: `string` — Combined string tracking project grouping identities.\r\n*   `contributors`: `Object` — Structural performer attribution map definitions:\r\n    *   `primary`: `ArtistPreview[]`\r\n    *   `featured`: `ArtistPreview[]`\r\n\r\n### `PlaylistPreview`\r\n*   `id`: `string | number` — The unique database or platform identifier for the playlist.\r\n*   `name`: `string` — Display moniker given to the designated digital collection folder record.\r\n*   `title`: `string` — Optional description subtext or alternative header mapping.\r\n*   `code`: `string` — Unique systemic reference identifier matching database route queries.\r\n*   `type`: `string` — Operational metadata category categorization tags (e.g. `\"user\"`, `\"editorial\"`, `\"smart\"`).\r\n*   `cover`: `Image` — Compilation artwork schema tracking active header layout designs.\r\n\r\n### `QueuePreview`\r\nThe aggregate array configuration documenting upcoming performance items loaded into the live execution stack buffer.\r\n*   `items`: `TrackPreview[]` — Active sequence list tracking tracks prepared for chronologically ordered playback execution.\r\n*   `playlist`: `PlaylistPreview | null` — Origin track context mapping if the sequence pipeline initialized out of a shared collection list folder.\r\n*   `release`: `ReleasePreview | null` — Origin studio record context map if the pipeline was populated from an Album or single release container.\r\n*   `artist`: `ArtistPreview | null` — Identity mapping reference if the playlist pipeline query was spawned dynamically out of an explicit artist page dashboard.\r\n\r\n---\r\n\r\n## 💡 Practical Implementation Snippets\r\n\r\n#### 1. Rendering an Interactive Waveform Progress Scrub Bar\r\nUsing the array inside `track.wave` paired with real-time `position` updates, you can draw a custom timeline with HTML bars or a Canvas context:\r\n\r\n```javascript\r\nplayerSdk.on('change', ({ type, payload }) => {\r\n    if (type === 'track') {\r\n        const waveData = payload.track.wave; // Returns exactly 100 amplitude values\r\n        renderWaveforms(waveData); // Spawn 100 stylized custom layout columns\r\n    }\r\n});\r\n```\r\n\r\n#### 2. Enhancing Queue Layout Rendering Speeds\r\nWhen constructing sidebars listing long indices inside `QueuePreview`, optimize layout processing cycles by binding your structural image source elements directly onto the compact asset `crop` endpoint:\r\n\r\n```javascript\r\nconst populateQueueSidebar = (queuePayload) => {\r\n    queuePayload.items.forEach(trackItem => {\r\n        const thumbNode = document.createElement('img');\r\n        // Binding onto crop (180x180) reduces frame execution cost inside the iframe sandboxed memory bounds\r\n        thumbNode.src = trackItem.cover?.crop || 'fallback-artwork.png'; \r\n        document.body.appendChild(thumbNode);\r\n    });\r\n};\r\n```\r\n\r\n---\r\n\r\n## 🪪 License\r\nThis SDK core package module distribution architecture is released under open-source MIT guidelines. Maintained exclusively for the extension development layers of the **Bilbo Music** digital audio engine.\r\n\r\n","readmeFilename":"README.md"}