Pira.cz Now Playing

Description

Pira.cz Now Playing receives metadata pushed by a radio automation system or any other application capable of making HTTP GET or POST requests. It displays the latest artist, title, and free-form text using simple WordPress shortcodes, without requiring a streaming server, external account, or paid service.

Features:
* Separate artist, title, and text shortcodes.
* Independent song (artist/title) and text channels, each with its own inactivity timeout.
* Configurable replacement text when the text channel times out.
* Automatic updates on the open page without a page reload.
* Non-breaking spaces for empty or expired artist/title fields to preserve layout.
* API-key authentication and a simple settings page with example requests.
* One station per WordPress installation.

Compatible with Magic RDS 4 Simple HTTP by Pira.cz and other applications that can send HTTP GET or POST requests. Magic RDS 4 configuration instructions are provided separately by Pira.cz.

Usage

The following shortcodes can be placed anywhere WordPress processes shortcodes:

[pira_now_playing] — displays the free-form text channel.

[pira_now_playing element="artist"] — displays the current artist.

[pira_now_playing element="title"] — displays the current song title.

Each shortcode renders a span element. The browser automatically checks for updated values at the configured refresh interval. The initial value is rendered by WordPress, so the shortcode works even before the first browser refresh.

Song and text are independent: sending artist/title does not refresh the text timeout, and sending text does not refresh the song timeout. You can use two independent HTTP senders, one for each channel.

When the song timeout expires, artist and title become non-breaking spaces to avoid collapsing their lines. When the text timeout expires, the configured replacement text is displayed.

HTTP API

The Update endpoint is displayed in Settings > Pira.cz Now Playing. On a typical installation it is:

https://example.com/wp-json/pira-now-playing/v1/update

Replace example.com and YOUR_KEY with your own site and API key.

Update a song using GET:

https://example.com/wp-json/pira-now-playing/v1/update?key=YOUR_KEY&artist=ABBA&title=Waterloo

Update the text channel using GET:

https://example.com/wp-json/pira-now-playing/v1/update?key=YOUR_KEY&text=Morning%20Show

Alternatively, use HTTP POST with form-encoded fields (application/x-www-form-urlencoded):

key=YOUR_KEY&artist=ABBA&title=Waterloo

or:

key=YOUR_KEY&text=Morning%20Show

The API also accepts the key in an X-PIRA-Key HTTP header for clients that support custom headers. Custom headers are not required for Magic RDS 4 Simple HTTP.

Include both artist and title in each song update. If only one is supplied, the other is cleared. Sending the text field only updates the text channel. If a request includes both song fields and text, both channels are updated.

All values must be URL-encoded correctly. For example, a space can be represented as %20, and an ampersand inside a field value as %26.

A successful update returns JSON with ok: true. Invalid or missing credentials return HTTP 403. A request without any supported metadata fields returns HTTP 400.

Public status endpoint (no API key needed):

https://example.com/wp-json/pira-now-playing/v1/current

It returns the current display values and channel status as JSON. Do not put private information in metadata fields: the displayed data and public status are accessible to visitors.

Security: Use HTTPS. API keys in GET URLs may be recorded in web-server, reverse-proxy, or monitoring logs. If the sender supports it, POST with the key in the custom HTTP header avoids placing it in the URL. Keep the key secret and replace it if exposed.

Styling

The output uses these CSS classes, which can be styled in your theme or WordPress Additional CSS:

• .pira-np — every field.
• .pira-np-text — text channel.
• .pira-np-artist — artist.
• .pira-np-title — title.

The plugin does not impose a visual design. Use your theme’s typography, layout, and CSS.