C
Castroid

Castroid Player Docs

A free web radio player with cover art, now-playing, visualizer, and recent tracks. Use the home page builder to generate an embed code and drop it into any site.

Quick Start

  1. On the builder, choose Direct (scheme://host[:port]/mount) or Proxy (scheme://host/proxy/user/mount) and paste your stream URL.
  2. Pick theme + accent, toggle visualizer/history, and set the preview height you want.
  3. Copy the iframe and paste it into your site (see examples below).

Relative (same domain):

html
<iframe src="/embed/player?endpoint=https%3A%2F%2Fmyradio.icecasthost.com%3A8002%2Fstream&name=Ma%20Fm&theme=dark&accent=487512&autoplay=0&compact=0&visualizer=1&history=1" style="width:100%;height:360px;border:0;overflow:hidden;background:transparent" allow="autoplay" loading="lazy" title="Castroid Player · V1"></iframe>

Absolute (any domain):

html
<iframe src="https://player.castroid.com/embed/player?endpoint=https%3A%2F%2Fmyradio.icecasthost.com%3A8002%2Fstream&name=Ma%20Fm&theme=dark&accent=487512&autoplay=0&compact=0&visualizer=1&history=1" style="width:100%;height:360px;border:0;overflow:hidden;background:transparent" allow="autoplay" loading="lazy" title="Castroid Player · V1"></iframe>

WordPress

Use a “Custom HTML” block and paste the iframe.

Wix / Squarespace

Add an Embed/HTML element and paste the iframe.

Plain HTML

Drop the iframe where you want the player to appear.

Embed URL & Options

The player lives at https://player.castroid.com/embed/player and is configured using query parameters.

endpointrequired
string (URL)
Your audio stream. Direct example: https://myradio.icecasthost.com:8002/stream. Proxy example: https://air.example.com/proxy/station/stream. Use HTTPS to avoid mixed-content errors.
name
string
Optional display name shown in the header.
theme
"dark" | "light"
UI theme for the player. Default: dark.
accent
hex (no #)
Accent color. Example: 487512.
autoplay
"1" | "0"
Attempt to start automatically. Browsers may block autoplay with audio—users can always press Play.
compact
"1" | "0"
Denser header for tight spaces.
visualizer
"1" | "0"
Toggle the audio visualizer.
history
"1" | "0"
Show recent tracks when available.

Tip

Keep the iframe tall enough for the options you enable. Full layout works well at ≥360px; compact layouts fit at ≈190px.

Size & Layout

Height is controlled by the style on your iframe, not a URL parameter. The builder shows the exact height used in your embed code.

  • Responsive width: use style="width:100%".
  • No scrollbars: the embed page prevents overflow; keep your height generous if you enable visualizer + history.

Direct vs Proxy

Direct

scheme://host[:port]/mount

  • Connects straight to your Icecast/Shoutcast mount.
  • Best when your stream is already on HTTPS.

Proxy

scheme://host/proxy/user/mount

  • Useful if origin is HTTP-only or on unusual ports.
  • Common with hosted radio panels and CDNs.

Versioning

The player is maintained as v1, with updates that keep embeds compatible. The version label in the builder header shows the currently deployed player version. You don’t need to change your iframe when minor updates ship.

  • Breaking changes would only occur in a new major version (e.g., v2).
  • If you must pin to a specific build, keep a copy of the working iframe code from the builder.

Troubleshooting

No audio / Autoplay blocked

  • Browsers can block autoplay with sound. Ask users to click Play once.
  • If your site has prior interaction (clicked anywhere), autoplay is more likely to work.

Mixed content (HTTP stream on HTTPS site)

  • Use an HTTPS endpoint, or switch to a proxy over HTTPS.

Nothing shows / 404

  • Open the iframe src in a new tab to verify the embed page loads.
  • Check that your endpoint is URL-encoded and publicly reachable.

Best Practices

  • Prefer https:// stream URLs.
  • Keep allow="autoplay" on the iframe and enable loading="lazy".
  • If you embed multiple players on one page, keep only one set to autoplay.