Frog Wizard

A userscript that shows a SoundCloud playlist's total runtime

I use SoundCloud a lot. I am often calculating the runtime of different sets of songs in order to tell a story within the length of one side of an LP. This userscript adds a small bit of text to to the bottom right corner of the page which looks something like Total: 1:02:03 · 14 tracks.

This page describes it in enough detail that you or a coding agent reading this page can rebuild it without the source.

Shape

One userscript file for Greasemonkey, Tampermonkey, or Violentmonkey.

Metadata key Value
@match https://soundcloud.com/*
@grant none
@run-at document-idle

It matches the whole site, not only playlist URLs. SoundCloud is a single-page app, so the script has to be running already when the user clicks through to a playlist from somewhere else.

When it runs

  1. Every 1000 ms, compare location.href to the last URL seen. Do nothing unless it changed. In-app navigation fires no page load, and polling is the simplest thing that catches every case.
  2. If location.pathname does not contain /sets/, hide the badge and stop. Playlists and albums both live under /<user>/sets/<slug>.
  3. Otherwise show Total: loading…, fetch the data, and replace the text with the result.

The first tick counts as a change, so a direct load of a playlist URL works.

Where the number comes from

SoundCloud's server-rendered HTML carries a script tag that assigns a JSON array to window.__sc_hydration. The script reads the total from there. It does not call SoundCloud's API, which would need a client_id.

  1. fetch(location.href, { credentials: 'include' }) and read the response as text. Refetch even though the page is already open: after in-app navigation the loaded document still holds the hydration data of whichever page was loaded first. The credentials are for private playlists.
  2. Extract the array with this expression, then JSON.parse capture group 1:
/window\.__sc_hydration\s*=\s*(\[[\s\S]*?\]);\s*<\/script>/
  1. Find the array element whose hydratable is "playlist". Its data object is the playlist.

Fields used from data:

Field Meaning
duration total runtime in milliseconds
track_count number of tracks
tracks array of track objects, each with its own duration in milliseconds when present

Use data.duration as the total. If it is missing or zero, fall back to summing duration over tracks. The fallback undercounts: only the first few tracks in the page data carry full metadata, and the rest are stubs with no duration. When that happens, append (only K/N tracks known) to the output, where K is the number of tracks that have a duration and N is tracks.length. Do not drop this note, or a partial sum looks like a real total.

The track count is data.track_count, falling back to tracks.length.

Output

Total: <time> · <count> tracks

Time formatting: round milliseconds to whole seconds, then print h:mm:ss if there is at least one hour, otherwise m:ss with unpadded minutes.

duration Shown
185400 3:05
3723000 1:02:03
45000 0:45

Every failure is shown in the badge in place of the total, prefixed with Total: : a non-OK HTTP status (with the code), no hydration data in the page, no playlist entry in the array (list the hydratable values that were found), or any thrown exception (with its message). Nothing goes only to the console. The markup is undocumented and will change, and the badge should say which step broke.

The badge

One div appended to document.body, created once and reused.

Property Value
position fixed
bottom 56px
right 12px
z-index 2147483647
background none
color inherit
font 13px/1.3 sans-serif
pointer-events none
display none until there is text to show

The 56px offset clears SoundCloud's fixed player bar at the bottom of the window. pointer-events: none keeps the badge from swallowing clicks on whatever is under it. No background and inherited color make it follow the site's light or dark theme.

Not included

#javascript #soundcloud #spec #userscript