Radio Cult Uploader for Strapi

Upload radio show episodes to Radio Cult and publish them onward to SoundCloud and Mixcloud — straight from the Strapi admin.

Built by Sister Midnight FM, a community radio station in South East London, for our own episode workflow — and made generic so any Radio Cult station running Strapi can use it.

What it does

• Uploader page in the admin: pick an episode, drag in the audio file (.mp3/.m4a, up to Radio Cult's 750MB limit), watch a real progress bar, and the track lands in your Radio Cult media library — with the episode's artwork embedded in the mp3's ID3 tag (Radio Cult has no artwork API; embedded art is the only way).
• One-click publish to SoundCloud and Mixcloud through Radio Cult's Connect endpoints, with title, tags, description and artwork.
• Automatic link write-back: when Radio Cult finishes transferring, the resulting SoundCloud/Mixcloud URLs are saved onto your episode entry automatically (checked every 10 minutes by a cron sweep, on page polls, and on demand). Publishes done by hand in the Radio Cult dashboard are picked up too.
• Edit-view side panel on your episode content type showing upload/publish state, with a button to open the uploader.
• Title sync: renaming an episode in Strapi renames the Radio Cult track.
• Works with your content model: a settings page maps your own content type and field names — nothing is imposed on your schema, and the plugin keeps its bookkeeping in its own hidden content type.
• Themeable: colour presets, a handful of colour overrides, a font (system or Google Fonts) and your own logo on the uploader page.

Requirements

• Strapi v5 (any 5.x, including installs still on the @strapi/design-system 2.0.0-rc line)
• Node 20+ (uploads stream files with fs.openAsBlob)
• A Radio Cult station with API access; third-party publishing (SoundCloud/Mixcloud) needs a Radio Cult plan that includes the Connect endpoints (Premium/Business or the Connect add-on)

Installation

npm install strapi-plugin-radiocult-uploader
# or: yarn add strapi-plugin-radiocult-uploader

Then raise the request body limit so full-size episodes can reach the plugin — Strapi's default is 200MB. In config/middlewares.ts (or .js), replace the 'strapi::body' line with:

{
  name: 'strapi::body',
  config: {
    formidable: {
      maxFileSize: 800 * 1024 * 1024, // Radio Cult accepts up to 750MB
    },
  },
},

Rebuild the admin (npm run build) and restart Strapi.

Setup

Open Settings → Radio Cult Uploader → Configuration:

1. Credentials — paste your Radio Cult API key and station ID, then hit Test connection. Prefer environment variables in production: RADIOCULT_API_KEY, RADIOCULT_STATION_ID and RADIOCULT_ENABLED always override what's stored here (the fields grey out when the env vars are set).

2. Field mapping — pick the content type your episodes live in. The plugin auto-matches fields by name and type; check them:

   | Mapping | Field type | Used for | |---|---|---| | Title (required) | string/text | Track title on Radio Cult | | Artwork image | media | Embedded in mp3s, sent to publishes | | Broadcast date | date/datetime | Default album name, e.g. "August 2026" | | SoundCloud link | string/text | The published URL is written here | | Mixcloud link | string/text | The published URL is written here | | Tags/genres relation | relation | Entries become publish tags (pick the label field too) | | Show relation | relation | Optional — names the uploader browser tab |

3. Publish defaults — default artist (your station name) and default publish description.

4. Uploader theme — pick a preset (Paper, Midnight, Slate), a font (the system font or one of the bundled Google Fonts), tweak the six main colours, and set a station name and a logo (upload the logo in the Media Library and paste its URL). The preview updates live. Google Fonts are fetched from fonts.googleapis.com / fonts.gstatic.com when a Google font is selected. If you have tightened strapi::security's CSP, add those hosts to style-src and font-src, or stay on System default.

5. Check Diagnostics at the bottom — it warns if your Node version or body-size limit will block uploads, or if cron is disabled.

Permissions

Any admin with access to your episode content type can use the uploader. The settings page is guarded by a dedicated permission — grant Radio Cult Uploader → Access the settings to non-super-admin roles under Settings → Roles → Plugins.

Using it

1. Open an episode in the Content Manager. The Upload to Soundcloud/Mixcloud/Radio Cult panel sits on the right (entries must be saved first).
2. Open Episode Uploader → a themed page opens with three steps:
   1. Track details — prefilled from the entry (title, artist, album, tags, description, artwork preview); edit freely, your Strapi entry is never changed by this form.
   2. Upload to Radio Cult — drop the audio file in. mp3s get the artwork embedded. Re-uploading asks before replacing the existing track.
   3. Publish — one button per platform. Radio Cult transfers asynchronously; the page polls and the link is written to your mapped link fields automatically. "Check for links now" forces a fresh look.
3. The activity log at the bottom keeps a timestamped record of everything that happened.

Notes & limitations

• One station per Strapi instance. The plugin talks to a single Radio Cult station.
• Mixcloud publishes may 402. Radio Cult's docs say 402 means "not on your plan", but their Mixcloud endpoint has been observed returning 402 Internal server error for every request even on plans where SoundCloud publishing works — a fault on Radio Cult's side. If that happens: publish the track by hand in the Radio Cult dashboard (Media → the track → Actions → Upload to Mixcloud). The plugin still detects the finished publish and saves the link to your entry (it watches recently uploaded tracks for up to 7 days).
• m4a artwork: artwork can only be embedded into mp3 files; m4a uploads reach Radio Cult without an image.
• Artwork formats: jpeg/png only; ≤10MB for embedding, ≤2MB for SoundCloud/Mixcloud publish artwork (the plugin picks the largest fitting size Strapi has generated).
• Rate limits: Radio Cult 429s are respected with automatic backoff; the UI tells you when to retry.
• Draft & Publish: link write-back writes directly to the stored entry (no publish cycle is triggered, and no other fields are touched).
• The plugin registers a cron job (*/10 * * * *) for link syncing — make sure cron is enabled in config/server.ts (cron: { enabled: true }) if you want links to land while nobody has the page open.

Migrating from a pre-plugin setup

If you previously wired Radio Cult uploads into your app with bookkeeping fields on your own content type (RadioCultTrackId, RadioCultUploadedAt, …), a migration script ships in the plugin repository:

RCU_DRY_RUN=true node scripts/migrate-from-fields.mjs   # from the plugin repo, run at your app root
node scripts/migrate-from-fields.mjs

It copies the old field values into the plugin's track-records (see the script header for the env vars that change the source content type/field names). Afterwards you can delete the old fields from your schema.

Environment variables

| Variable | Effect | |---|---| | RADIOCULT_API_KEY | Radio Cult API key (overrides the settings page) | | RADIOCULT_STATION_ID | Radio Cult station ID (overrides the settings page) | | RADIOCULT_ENABLED | false switches the whole integration off |

Development

npm install
npm run build        # build admin + server bundles
npm run watch:link   # develop against a local Strapi app via yalc
npm run verify       # pre-publish checks

License

MIT

Issues

Bugs and feature requests: GitHub issues.