Music Automation

Music Automation lets RKHM build and maintain your music catalog for you. Instead of adding every artist, album and track by hand, RKHM can pull metadata from Spotify and MusicBrainz, and attach playable sources from YouTube or SoundCloud.

There are three separate mechanisms behind the feature. They are configured on the same screen, but they are triggered in completely different ways and they do different things. Reading this table first will save you a lot of confusion later.

In short: Cronjobs grow your catalog deliberately and on a schedule you control, Full Automation grows it as a side effect of people browsing, and on-demand fetch is a safety net for a track someone tries to play that has no audio attached yet.

Before you start: credentials

All automation settings live on one page: Admin area → Content → Music → Automation. The same page is also linked from Settings → Cronjob → Music - Automation.

Get Spotify credentials by creating an app at Spotify for Developers, using an account with an active Premium subscription. Get a YouTube key by enabling YouTube Data API v3 in Google Cloud. If you have installed the Spotify Multi Accounts tool, the Client ID and Secret fields on this page are replaced by a note — define your keys on that tool's own settings page instead.

Mechanism 1 — Full Automation

Enable it with Full Automation in the Spotify group. When it is on, RKHM talks to Spotify live, while a visitor is browsing, and merges what it finds into the page it is about to render.

How it works

• When a visitor searches your site, RKHM also searches Spotify and adds closely-matching artists and albums that you do not already have into the search results. Clicking one creates it on your site.
• When a visitor opens an artist page, RKHM re-checks that artist on Spotify and pulls their albums — and creating those albums creates the tracks and the artists credited on them.
• When a visitor opens an album page, the same thing happens one level down: the album's tracks are pulled, and every artist credited on them is created if missing.
• Any artist RKHM encounters in a Spotify response gets a row in your database — lead artists, featured artists, and, if a scrapper tool is installed, related artists too.
• It is deliberately disabled during background cron runs — it is a live, per-page-view mechanism only.

When Full Automation is the wrong choice

1. Curation: you lose control of what is in your catalog. Anything a visitor searches for, and everything related to anything they open, can end up on your site permanently.
2. Database growth: the expansion described above is unbounded. Plan for it, or avoid it.
3. High traffic: thousands of visitors a day means thousands of live Spotify calls, and you can reach Spotify's limits.
4. Speed: RKHM has to wait for Spotify's servers before answering the visitor. Pre-collecting with cronjobs is always faster.
5. Missing sources: items created this way still need an audio or video source attached, which takes extra time at exactly the wrong moment.

Mechanism 2 — On-demand source fetch

This is the quietest of the three, and the one most often misunderstood. It is controlled by two toggles: Enable YouTube as Music Source (Youtube group) and Enable SoundCloud as Music Source (Soundcloud group).

When a visitor presses play on a track that has no working source, RKHM searches YouTube or SoundCloud for that single track, and — if it finds a good match — stores it as a new source on that track so playback can start. No admin action, no cronjob, resolved inside that one request. If Youtube Download → Active is also on, RKHM can instead download the video and convert it to a local MP3.

Two related toggles sit in the same Youtube group. Enable Replacement of Broken YouTube Videos lets the player report unavailable videos back to your server, so they can be found and replaced. Enforce 30-Day YouTube ID Storage Limit makes RKHM delete stored YouTube IDs after 30 days, to comply with YouTube's API policies.

Reporting is throttled so it cannot be abused. The limits live on Settings → Player → Report Limits, and they apply to every kind of reportable source, not only YouTube videos: Max Reports per User per Item (default 1), Max Reports per IP per Item (default 1), and Max Reports per IP per Day (default 10, counted as unique items).

Mechanism 3 — Music Cronjobs

Think of music cronjobs as diligent carriers working behind the scenes. Each one travels to Spotify, MusicBrainz or YouTube, collects what you told it to collect, and brings it back to your server without you doing anything. You control what they collect, how often, and how much per trip — which is exactly what Full Automation does not give you.

You manage them at Admin area → Content → Music → Cronjobs (also linked from Settings → Cronjob → Music - Cronjobs). Create as many as you like, each with its own purpose and its own schedule. More jobs means more API requests and more database work, so build them deliberately rather than all at once.

Anatomy of a music cronjob

Static IDs vs Dynamic IDs

Static means you hand the job a fixed list of API IDs, one per line. This is how you seed a catalog: pick ten artists you care about and let the job fetch them and everything attached to them. Use the Browse Spotify button next to the field — type a keyword, click a result, and its ID is added to the list for you.

Dynamic means the job looks into your own database instead, and you narrow it down with Dynamic Filter fields — the same filters you use when browsing artists, albums or tracks in the admin area. This is how you keep an existing catalog fresh, and how you enrich items you already have.

Two things are worth knowing about dynamic jobs. A dynamic Spotify job only picks up items that already carry a Spotify ID — it refreshes what you have, it does not discover new items. A dynamic MusicBrainz artist job with Get related artists enabled can create new artist entries as it discovers relations, which means its scope can keep expanding run after run. Watch that one.

What each API can do

A YouTube job skips any track that already has a YouTube source, and with Download videos on it also skips tracks that already have a local audio source — so it never re-does work it has already done.

Creating a cronjob, step by step

You can also restrict which days of the week a job is allowed to run, on Settings → Cronjob → Setting. This works for music jobs exactly as it does for RKHM's built-in ones.

Tuning: the three intervals

Execution Interval: how frequently the job runs, in minutes. 60 means up to 24 runs a day. By default jobs are executed one after another, so consider how many other jobs you have running. With Parallel execution turned on under Setting → Cronjob → Setting (added in v2.1.04), each due job starts as its own background process, up to the limit you set. If you are not sure, 10 minutes is a good baseline.

Update Interval: how current the data stays, in days. 1 means every ID is re-synced daily; 365 means annually. Frequent updates only make sense for dynamic content, like popular artists who release often. Most albums and tracks barely change, so a high number there is both more suitable and much cheaper on your API quota.

Item Limit: how many items are processed per run. Lower means fewer API requests per run. Note that one item is not one API request — a playlist can cost hundreds of requests if it contains hundreds of entries, and an artist with Get albums enabled costs far more than a bare artist lookup.

Create several cronjobs for different purposes. Set Item limit to 1 and Execution interval to 10 for all of them, then give each one a different Update interval based on how often that kind of content actually changes on the source.

General advice

Reading the stats box

The cronjob list screen shows a live Stats box for every job. Use it to judge whether a job's settings can actually keep up with the set of items you pointed it at.

• Execution interval and Update interval — repeated back to you for quick comparison
• Max up-to-date items — an estimate of how many items this job can realistically keep current, based on your intervals, your item limit, and how expensive that object type is to fetch
• Query type — Static or Dynamic
• Query item count — how many items the job's query covers in total
• Checked item count — how many of them have been checked recently enough to still count as up to date
• Queued for check count — how many are waiting their turn

If Queued for check count never goes down, the job is not keeping up: raise the item limit, lower the execution interval, or raise the update interval so items stay valid longer.

Worked examples

Example 1 — seeding a hip-hop catalog. Create a job called Seed. API Name: Spotify. Object type: Artist. Dynamic IDS: off. Update interval: 1. Enable Get albums and Sync genres. Use Browse Spotify to add the IDs of ten artists you care about. Each run collects those artists along with their albums and tracks.

Then add a Famous Checker: same API and object type, but Dynamic IDS on, update interval 7, with a dynamic filter that narrows the selection to the artists you most want kept current. Add a Mid Checker alongside it with an update interval of 60 and a looser filter, so your less-critical artists are still refreshed, just far less often.

Example 2 — enriching what you already have. For a Development Mode app affected by Spotify’s endpoint and metadata restrictions, use MusicBrainz to enrich existing artists with genres, tags, and related artists. Create a job with API Name: MusicBrainz, Object type: Artist, Dynamic IDS on, update interval 14, and enable Get genres and Get tags. It will walk your existing artists and fill in the metadata Spotify used to provide. Add Get related artists only if you are comfortable with the job creating new artist entries as it discovers relations.

Example 3 — attaching playable sources. Create a job with API Name: YouTube, Object type: Track, Dynamic IDS on (both are required). Give it a high update interval — an already-attached source does not need re-collecting. Use the dynamic filters to narrow it to the tracks you actually want playable, especially if you enable Download videos, so you are not downloading and converting your entire catalog.

Collecting sources

Metadata alone is not enough — an item also needs something with sound. RKHM supports three ways to get there.

1. YouTube video: found either in the background by a YouTube cronjob, or on demand at the moment a visitor presses play.
2. SoundCloud audio: fetched per visitor request only. There is no scheduled SoundCloud import — see the limits section below.
3. YouTube video converted to MP3 (youtube-dl): available both on demand and via a cronjob. Because downloading and converting takes real time, cronjobs are strongly preferred so nobody waits — and use dynamic filters so you do not convert your entire catalog. Note the disclaimer near the top of this article before you enable it.

For YouTube and SoundCloud either approach is fine — once the ID is found it is stored, and no further API requests are made for that item. For youtube-dl, use cronjobs. And always give source-collecting cronjobs a large update interval: there is no reason to re-collect a source you already have.

Housekeeping jobs

Two settings register their own background jobs automatically — you do not create these on the Cronjobs screen, you just switch the setting on.

• Enforce 30-Day YouTube ID Storage Limit adds a daily job that deletes stored YouTube sources older than 30 days.
• Delete singles after EP release adds a daily job that looks for albums with the same title and artist, and where it finds exactly one studio album plus one or more singles, removes the duplicate singles.

Not automation, but related: the Bulk Importer

If your music is already on your own disk rather than on a third-party service, none of the above applies — you want the Bulk Importer tool instead. Its Music Bulk Import job scans an upload folder, reads each audio file's ID3 tags (title, album, album artist, featured artists, embedded cover art) and creates the matching artists, albums and tracks for you. It is a one-directional import of files you already have, not a sync with an external API. See Bulk Importer for the details.

Monitoring

• Settings → Cronjob → Run logs is the main screen. Each row shows the status, start and end time, and a detail message — either the job's own summary such as 'Checked 12 item(s)', or the error that stopped it.
• Every active music cronjob has a Logs button on the list screen that opens the run logs already filtered to that job.
• Finer per-step progress lines are recorded during each run, which is where you see individual lookups and failures.
• The admin dashboard shows a Music Cronjobs card with the total number of jobs configured.
• Error logs in the admin area will show you whether you have hit an API limit.

Limits and constraints

Is it legal?

Check the current Spotify, YouTube, and SoundCloud terms, including permissions for API access, scraping, downloads, and attribution, before using these integrations in a public app. Access credentials and source links do not by themselves grant rights to redistribute content.