Integrations

How to integrate the music request widget

Guide to enable Request Desk in stream settings and integrate the widget via CDN script.

The music request widget is integrated via CDN and a script with type="module". At the moment, this is the only supported integration method (npm module is not used for production integration yet).

1) Enable Request Desk in stream settings

Before integrating on your website, open the target stream settings page in Tunio Control Panel and enable Request Desk.

Available modes:

  • All genres: listeners can request tracks from the full catalog (all categories).
  • On-air genres: listeners can request only genres currently used by the active on-air playlist.
  • Disabled: request widget is effectively turned off.

On the stream settings page, copy the stream UUID (ID) from the top section. This UUID is required for widget initialization.

2) Request limitations

  • A track will not be sent to on-air playback if it was already played within the last hour.
  • Per-IP limit: no more than one request every 30 minutes.

3) Connect the widget on your website

  1. Add widget styles

    HTML
    <link rel="stylesheet" href="https://cdn.tunio.ai/build/track-requests/v1.0.0/style.css" />

  2. Add widget script as module

    HTML
    <script type="module" src="https://cdn.tunio.ai/build/track-requests/v1.0.0/music-request-widget.js"></script>

  3. Call initialization after script load

    JS
    window.TunioMusicRequestWidget.init({
  streamUuid: "your-stream-uuid",
  queueTargetId: "music-order-queue",
  buttonTargetId: "music-order-button",
  lang: "en",
  theme: "dark"
})

init parameters

  • streamUuid: string - stream UUID (required).
  • queueTargetId?: string - queue container ID.
  • buttonTargetId?: string - open-button container ID.
  • lang?: "ru" | "en" - widget language. Default: en.
  • theme?: "dark" | "light" - base theme. Default: dark.
  • showQueue?: boolean - show queue block. Default: true.
  • themeVars?: Record<string, string> - CSS variable overrides for custom design.

Requirement: provide at least one mount target (queueTargetId or buttonTargetId).

Style customization

You can override widget styles to match your website design via themeVars and/or your own CSS rules on top of widget classes.

It is recommended to pin a specific CDN version (for example, v1.0.0) in production and update it only after testing.