Custom Widget to Simplify Display


I was wondering if there is a way to build a custom widget that looks like a player. It will simply display a few things:

  • Current show art or song art
  • Current show title, date, hours, and DJ
  • A button to listen live

I am aware that most of those can be retrieved from the current JS widgets, and I did something like that on kspc[dot]org. However, to achieve that, I used a lot of CSS to hide and move things around. I wish there was a simpler widget that would do that more efficiently.

It’s very tricky to handle that when there is a show with no playlist, or there is a gap in the schedule, or a song without art. The current widget has different HTML structures for each thing, which makes it harder to deal with and I keep finding things that don’t work with what I am truing to do, for example:

The main goal of the new simpler widget would be to:

  • If there is no show playing at the moment, display the upcoming show, instead of being stuck on the last show that aired.
  • Display the details of the current show only; there’s no need to have a separate div for the current playlist. We don’t need any details about the playlist, just the show details.
  • The button to listen live would play what is on-air live, not only the current song track.
  • Get the show art when there is no song art or no playlist playing.

Do you think something like that would be possible? We work with three different radios that could use that simplified widget. I am happy to help however I can!


Yes, this is certainly possible if you use the Spinitron API (reference and demo/tutorial). I think it would be hard to do what you described using Spinitron’s available pages/widgets modified by client-side JS and CSS.

You’ve been thinking about the specs for the algorithm that chooses what to display. I would to add some things you might consider, speaking as keeper of the database itself.

There are a surprising number of scenarios to work through to decide how such a widget should behave.

  • There can be zero one or more playlists that are “current”, i.e. already started but not yet finished.
  • Same for current occurrences of shows in the schedule.
  • The time since the last spin began can vary a lot.
  • So can the time since the most recently ended playlist and show occurrence.
  • There might be only short time to the next scheduled show occurrence or playlist.

The algorithm for what to prioritize and display depending on the current state of the database is ideally up to the individual station (i.e. should preferably be customized by the station) because their approach to scheduling and how staff are trained/expected to create playlists would factor in.

Every station in Spinitron has a landing page e.g. We had to design a general algorithm that would be just about good enough for all stations to choose what to put there. But having a whole page makes the problem easier.

You asked about a widget, a word that suggests something much smaller.

If you don’t feel able to write an API client, I may be able to help with that if we can get one or two other stations interested and a clear technical spec. Potentially if the widget looks good on paper and in a mock-up then maybe we can add it as a new Spinitron feature.

Hi Tom, thanks for all the details! I’ll look into the API and see what I can do. I’ll let you know once I have something done, and we can discuss the possibility of adding it as a new Spinitron feature depending on what I am able to do.

1 Like

This kind of can go in a few different directions.

  1. The simplest is if you do something just for Tech support for web integration projects is included in the service for all Spinitron clients so you’re not on your own with that.

  2. Alternatively you could try to make something that multiple stations might be able to use and publish the work on GitHub. A lot of Spinitron stations run WordPress so maybe it’s feasible to write a simple caching PHP API client that runs on the same server. It can implement the algorithm to select what to display at any given time. Then there’s an HTML/CSS widget, maybe with some JS or maybe not. Our API demo is an example using zero server dependencies other than PHP itself.

  3. Finally, if stations aren’t really able to put that sort of thing on their WP server then it’s really a matter of developing a new feature for Spinitron. You persuade us that your elegant functional design should be hosted on our servers. In this case we would code the server-side logic and it would remain proprietary but the client side HTML/CSS/JS could be yours (in which “you” might not be just you personally, of course). The client side parts could potentially be on GitHub and be something Spinitron depends on.

And I have a question. Since you mentioned wanting to have a stream player as part of the widget, do you have any ideas how to make it continue to play as the user navigates to other pages?

Hey Tom,

I’ve spent some time playing with the API and managed to create a very straightforward player UI that displays everything I wanted. Because it’s so simple, this player doesn’t have the issues I’ve been dealing with while attempting to adapt the existing JS widget. It’s much easier to make it responsive too, since there are so few elements.

In terms of the UI, my requirements were quite simple:

  • Display the show’s image art (if available; otherwise, I’ll have a placeholder set with CSS).
  • Indicate the status as either “On air” or “Up next.”
  • Display the show title.
  • Show the time duration from start to end in the correct timezone.
  • Show the DJ’s name.

I’ve attached a screenshot of my demo for your reference (see screenshot-1.jpg below). The current show is marked with the “On air” status, while the others are labeled as “Up next.” I’ve included five shows to illustrate, but we’ll only display the first one on the actual websites. I also wanted to run a loop to test how the UI would handle schedule gaps, and as highlighted in yellow, it correctly displays the next day’s shows with an “Up next” status once we reach those gaps.

Unlike the existing player adaptation I implemented on, the new, simplified version won’t get stuck on a show that has already ended (see screenshot-2.jpg below) in scenarios such as schedule gaps, absence of a playlist during a show, or when the currently playing song lacks an associated image. These are all minor issues that our clients have expressed dissatisfaction with.

However, this new UI doesn’t yet have the capability to actually play the livestream; it only shows what’s on air. I believe we may need to utilize another plugin for that function since I haven’t found a way to achieve it using Spinitron alone. On, I use another plugin to create the Play button, and I position it on top of the Spinitron “player” UI. That works fine.

What do you think of it? Do you think there are any issues I am overlooking with this implementation?


Here are larger versions of those screenshots, in case those are hard to read:

I think it’s tremendous. Simply tremendous. It’s a simpler and for that reason arguably better demo of the API than my one. I love your use of “straightforward” and “simple” in describing it.

Spinitron itself is not at all involved in playing livestreams. In the simplest possible implementation you need a play/pause button UI and to initialize the browser’s media player with the stream URL. Some small amount of CSS & JS should suffice. But in the past people have found that compatibility across browsers and devices leads to using a compatibility layer to handle those differences. Then there are UX questions that are different on mobile devices, e.g. a pop-up player might be good on desktop but on a phone you want a play/pause UI in “notification”-style window separate from the browser.

So you might consider using two separate widgets: one for the player and one for the display of Spinitron content.

Can you put your code in Github so that we can make review comments and suggestions?

Hey Tom, I’m so glad you think that’s a good solution! Thank you for taking a look at it :smile:

I’ve put my code on Github. This is the only file I’ve edited:

I am thinking of making a WP plugin with it. To begin with, it would have only two fields: One for the Spinitron API key and another for the livestream URL. That is all I need for my three existing radio websites, but I can always add more features as needed in the future.

1 Like

Thanks for putting this on github. I’ve felt pretty comfortable with using the API for our own little player, but this is nicer than anything I would have put together.


Hey Tom,

I’ve just created a pull request at Introduce Simplified Player UI by madebycinza · Pull Request #2 · spinitron/v2-api-demo · GitHub.

I’ll go ahead and delete the other repository. I wasn’t sure initially if you wanted to merge my code with your main repository on GitHub, but I’m glad to hear that you do! I’m looking forward to collaborating :smile:

Is there any way we can turn this into a Wordpress plugin? I am good with Wordpress but bad at understanding what I’m supposed to do with GitHub repositories.

Or maybe someone could walk me through how to integrate this on my Wordpress site? I don’t see anywhere on the Spinitron site where I can submit a support ticket.

Thanks in advance!