tal-reusable-radio-widget

A plug-and-play React radio player widget for TALRadio. Connects to Firebase Realtime Database for live stream data and fetches available language channels from your API.

Features

• Live channel switching with language pill buttons
• Auto-selects default language — from prop or API isDefault flag
• Smart overflow — shows ... on hover when channels don't fit the width (minimum 3 always visible)
• Selected channel is always shown first
• Real-time streaming data (title, thumbnail, producer, RJ) via Firebase
• Listener count tracking per channel (join/leave)
• Volume control with mute toggle
• Live clock display
• Works in React and Next.js (App Router)

Installation

npm install tal-reusable-radio-widget

Peer Dependencies

Install these in your project if not already present:

npm install react react-dom firebase lucide-react

Import

import { LiveRadioWidget } from "tal-reusable-radio-widget";
import "tal-reusable-radio-widget/style.css";

Usage

React (Vite / CRA)

import { LiveRadioWidget } from "tal-reusable-radio-widget";
import "tal-reusable-radio-widget/style.css";

const firebaseConfig = {
  apiKey: "YOUR_API_KEY",
  authDomain: "YOUR_PROJECT.firebaseapp.com",
  databaseURL: "https://YOUR_PROJECT.firebaseio.com",
  projectId: "YOUR_PROJECT_ID",
  storageBucket: "YOUR_PROJECT.appspot.com",
  messagingSenderId: "YOUR_SENDER_ID",
  appId: "YOUR_APP_ID",
};

function App() {
  return (
    <LiveRadioWidget
      firebaseConfig={firebaseConfig}
      apiBaseUrl="https://your-api.com"
      defaultLanguage="hindi"
    />
  );
}

Next.js (App Router)

The widget uses client-side hooks and Firebase listeners — wrap it in a "use client" component:

// components/RadioClient.tsx
"use client";

import { LiveRadioWidget } from "tal-reusable-radio-widget";
import "tal-reusable-radio-widget/style.css";

const firebaseConfig = { /* your config */ };

export default function RadioClient() {
  return (
    <LiveRadioWidget
      firebaseConfig={firebaseConfig}
      apiBaseUrl="https://your-api.com"
      defaultLanguage="hindi"
    />
  );
}

Then use <RadioClient /> in any server or client page.

Props

| Prop | Type | Required | Description | |-------------------|----------|----------|---------------------------------------------------------------------------------------------------------| | firebaseConfig | object | Yes | Your Firebase project config object | | apiBaseUrl | string | Yes | Base URL of your backend API (e.g. https://api.example.com) | | defaultLanguage | string | No | Channel to select on load (e.g. "hindi", "telugu"). Falls back to isDefault flag from the API |

Default Language Resolution

The widget picks the initial channel in this order:

1. defaultLanguage prop — matched case-insensitively against channel names
2. isDefault: true in the API response — if no prop is provided or no match found

// Prop takes priority
<LiveRadioWidget ... defaultLanguage="telugu" />

// Falls back to API isDefault
<LiveRadioWidget ... />

Language Selector Behavior

• All live channels are shown as pill buttons
• Selected channel is always shown first
• When width is too narrow to show all, a ••• button appears after the first 3 visible channels
• Hover over ••• to see remaining channels in a dropdown
• Clicking any channel in the dropdown selects it

API Contract

The widget calls:

GET {apiBaseUrl}/talradio/channels?includeAll=false

Expected response:

{
  "data": [
    {
      "_id": "abc123",
      "name": "hindi",
      "isLive": true,
      "isDefault": true,
      "rank": 1,
      "voiceCommandLabel": "Hindi"
    },
    {
      "_id": "def456",
      "name": "telugu",
      "isLive": true,
      "isDefault": false,
      "rank": 2
    }
  ]
}

Channel name "talradio" is displayed as "English" in the UI.

Firebase Realtime Database Structure

The widget reads and writes these paths:

| Path | Purpose | |------|---------| | /currentStreaming/{channel} | Live stream data: title, thumbnailUrl, downloadUrl, producer, rjUserId | | /seekTime/{channel} | Current seek position of the live stream | | /talRadioCurrentListeners/{channel}/{listenerId} | Active listener tracking per channel | | /talRadioListenersCount/totalListeners | Global listener count (atomic increment/decrement) | | /talRadioListenersCount/totalChannelListeners/{channel} | Per-channel listener count |

Make sure your Firebase Realtime Database rules allow read/write access to these paths for your users.

Styling

Import the stylesheet once at your app's entry point or in the component that uses the widget:

import "tal-reusable-radio-widget/style.css";

All widget classes are prefixed with package-tal- to avoid conflicts with your app's styles.

Build & Publish (for maintainers)

npm run build   # outputs to dist/
npm publish

Output files:

| File | Format | |------|--------| | dist/index.esm.js | ES Module | | dist/index.cjs.js | CommonJS | | dist/index.d.ts | TypeScript types | | dist/assets/style.css | Styles |