Troubleshooting Tips for Pulsradio Widget — Common Problems and SolutionsIf your Pulsradio Widget isn’t working as expected, this guide walks you through common issues and practical fixes. It’s organized by symptom so you can quickly find relevant steps, with tips for diagnostics, configuration, and performance optimization.
1. Widget won’t load at all
Common causes: missing script, incorrect URL, blocked resources, or JavaScript errors.
- Check the script tag:
- Ensure the widget’s script URL is correct and accessible.
- If you’re using a CDN, open the script URL directly in your browser to confirm it loads.
- Inspect the browser console (DevTools → Console) for errors:
- Look for ⁄403 errors (resource not found / forbidden).
- Look for uncaught JavaScript exceptions; they often point to missing dependencies or syntax errors.
- Verify CSP (Content Security Policy) and mixed-content issues:
- If your page is HTTPS but the widget script is HTTP, the browser will block it.
- Add the widget’s domain to your CSP allowed script-src and connect-src directives if needed.
- Check ad blockers and privacy extensions:
- Some blockers may hide or block the widget. Test in an incognito window with extensions disabled.
2. Widget loads but shows a blank area
This can happen when CSS hides the widget, dimensions are zero, or initialization fails.
- Verify container element:
- Ensure the target container exists and has non-zero width/height.
- Make sure CSS isn’t setting display:none, visibility:hidden, or height:0.
- Check for CSS conflicts:
- Global CSS rules (e.g., iframe, .widget, img { display: block; }) may affect the widget. Use DevTools to inspect computed styles.
- Initialization timing:
- If you insert the widget before the DOM is ready, initialization might fail. Wrap widget creation in a DOMContentLoaded or defer the script.
- Look for runtime errors in Console indicating initialization problems.
3. Audio won’t play
Autoplay restrictions and browser policies often prevent autoplay.
- Autoplay policies:
- Many browsers block autoplay unless the user interacted with the page. Require a user gesture (click/tap) to start playback.
- Cross-origin audio issues:
- If audio is loaded from a different domain, CORS headers must be set correctly on the audio server.
- Check audio element state:
- Use DevTools Audio/Media panel and Console to inspect play() promise rejections.
- Volume and mute:
- Ensure the widget or browser tab isn’t muted and the audio element’s volume>0.
4. Buffering, stuttering, or connection drops
Network or stream encoding issues typically cause playback interruptions.
- Test stream URL directly:
- Open the stream URL in a media player (VLC) to confirm stability.
- Server-side load:
- High server load or insufficient bandwidth causes drops. Check server metrics and scale if necessary.
- Use adaptive/buffered playback:
- Increase buffer size or use adaptive streaming if supported.
- Check encoding and bitrates:
- Very high bitrates may be problematic for mobile users or slow networks. Offer a lower-bitrate fallback.
5. Wrong stream or metadata (title/artist) not updating
Metadata problems originate from the stream source or parsing logic.
- Confirm stream metadata:
- Use tools (e.g., streamlink or VLC) to inspect ICY/SHOUTcast metadata from the source.
- Metadata parsing:
- Ensure the widget correctly parses ICY headers or uses a metadata API. Some streams need periodic polling.
- Caching layers:
- CDN or proxy caching may delay metadata updates. Configure cache headers to allow fresh metadata if needed.
6. Widget looks broken on mobile or responsive issues
Responsive design and touch interactions need special handling.
- Responsive container:
- Use fluid widths and max-width rather than fixed pixel sizes.
- Touch targets and controls:
- Ensure play/pause buttons are large enough and not overlapped by other elements.
- Test across browsers and devices:
- Emulate mobile in DevTools and test on real devices for accurate results.
7. CSS or iframe conflicts
If the widget is embedded via iframe, some CSS issues are avoided, but sizing and cross-domain interaction can be problematic.
- Prefer iframe for isolation:
- Use an iframe if host page CSS frequently conflicts with widget styles.
- Communicate via postMessage:
- For interactions between iframe and parent, use window.postMessage with a defined protocol.
- Auto-resize iframe:
- Use a resize message to adjust iframe height based on widget content.
8. Errors when embedding in popular platforms (WordPress, Wix, Squarespace)
Platform-specific quirks can block scripts or sanitize HTML.
- WordPress:
- Use a custom HTML block or a plugin that allows unfiltered script tags. Some hosts disable script insertion; use a plugin to enqueue scripts properly.
- Wix/Squarespace:
- These builders may restrict external scripts. Use their provided “embed” features or follow platform docs for third-party widgets.
- Shortcodes and sanitizers:
- Ensure the editor isn’t stripping required attributes or tags.
9. Security considerations
Keep the widget secure to avoid introducing vulnerabilities.
- Sanitize inputs:
- If the widget accepts user input (e.g., station URL), validate and sanitize on both client and server.
- Use HTTPS:
- Serve widget assets and streams over HTTPS.
- Content Security Policy:
- Add necessary domains to CSP to avoid violations while minimizing allowed sources.
10. Diagnostic checklist & sample debug steps
- Open DevTools → Console: note any errors or warnings.
- Network tab: confirm all widget resources (JS/CSS/audio) return 200 and correct MIME types.
- Elements tab: check container visibility, size, and computed styles.
- Test stream externally (VLC/browser) to rule out server issues.
- Disable extensions and test in incognito to rule out blockers.
- Try embedding the widget in a minimal blank HTML page to isolate environment issues.
Example minimal test HTML:
<!doctype html> <html> <head> <meta charset="utf-8"> <title>Pulsradio Widget Test</title> </head> <body> <div id="pulsradio-widget"></div> <script src="https://example.com/pulsradio-widget.js" defer></script> <script> document.addEventListener('DOMContentLoaded', function() { PulsradioWidget.init({ container: '#pulsradio-widget', streamUrl: 'https://stream.example.com/stream' }); }); </script> </body> </html> 11. When to contact support
Contact Pulsradio support if:
- The stream is confirmed working externally but the widget fails.
- You see server-side errors (5xx) when fetching widget resources.
- You suspect an issue with the widget’s hosted script or API.
Include these in your support request:
- Browser and version
- Page URL where the widget is embedded
- Console errors and Network log screenshots
- Steps to reproduce
If you want, I can convert this into a step-by-step printable checklist, a troubleshooting flowchart, or tailor fixes for a specific error message you’re seeing.
Leave a Reply