useMediaMetadata

Subscribes to currently playing media information streamed from the Fluxlay desktop app. Retrieves track title, artist, album artwork, and playback state from system media players such as Spotify and Apple Music.

Import

import { useMediaMetadata } from "@fluxlay/react";

Signature

function useMediaMetadata(options?: MediaMetadataOptions): MediaMetadataInfo;

Parameters

MediaMetadataOptions

Property	Type	Default	Description
`intervalMs`	`number`	`1000`	Polling interval in milliseconds.

Return Value

Property	Type	Description
`title`	`string \| null`	Track title.
`artist`	`string \| null`	Artist name.
`album`	`string \| null`	Album name.
`artwork`	`string \| null`	Artwork image as a data URL (`data:image/...;base64,...`).
`duration`	`number \| null`	Track duration in seconds.
`elapsedTime`	`number \| null`	Elapsed playback time in seconds.
`playbackRate`	`number \| null`	Playback rate (0.0 = paused, 1.0 = playing).
`isPlaying`	`boolean`	Whether media is currently playing.

Returns all fields as null (isPlaying as false) until the first event is received.

Example

function Wallpaper() {
  const { title, artist, artwork, isPlaying } = useMediaMetadata({ intervalMs: 1000 });
 
  return (
    <div style={{ display: "flex", alignItems: "center", gap: 16 }}>
      {artwork && <img src={artwork} alt="Album art" width={120} />}
      <div>
        <h2>{title ?? "Nothing playing"}</h2>
        <p>{artist}</p>
        <p>{isPlaying ? "▶ Playing" : "⏸ Paused"}</p>
      </div>
    </div>
  );
}

Combining with useProperties

Combine with useProperties to let end users adjust the polling interval.

function Wallpaper() {
  const props = useProperties();
  const meta = useMediaMetadata({ intervalMs: props.updateInterval as number });
  // ...
}

Notes

On macOS 15.4 and later, a JavaScript for Automation (JXA) based adapter is used to access the system's Now Playing information.
Media information is updated in an event-driven manner (on track change, play/pause). Elapsed time is interpolated on the backend.
Artwork is provided as a data URL (Base64-encoded), ready to use directly in an <img> tag's src attribute.
This hook only works inside the Fluxlay desktop app. In a normal browser, it returns the initial default values.
When options values change, the stream is automatically reconnected.