User Guide

1. Quickstart (5–10 minutes)

2. Admin Overview (Menus & Areas)

In the WordPress admin area, the most important sections appear as submenu entries under The Studio Player.

Menu	Purpose	Typical use
Dashboard	Status, entry point, quick links	Jump straight to Muxer/Builder
Muxer-Uploader	Upload variants, mux, provide FLAC output	Create new projects/track versions
Player-Builder	Create playlists/players (custom post type)	Maintain playlist, adjust design, copy shortcode
Settings	Streaming, security, debug, onboarding, uninstall behavior	Fine-tuning for operations/performance
Tools	Maintenance & diagnostics (Integrity Scanner, Sample Data, Pro tools)	When files are missing, inconsistencies, migration
Help	Help/links/docs (partly remote, opt-in)	Quick reference and documentation
License & Account	License/account status (Freemius / Pro)	Upgrade, verify license status

2.1 Dashboard, Onboarding & Remote Content

The Dashboard is your entry point: version/plan status, quick links, and (optionally) an onboarding overlay. Onboarding can load additional content (guide, docs, changelog, security notices) from studioplayer.de.

• Onboarding overlay: On first use, a dialog may appear to ask whether remote content is allowed.
• Remote opt-in (Yes/No): If enabled, the admin can show embedded docs; if disabled, you only get links to the website.
• What is sent? Requests include e.g. plugin version, plan (free/pro), and site language (locale). No site content or user data is sent. Standard HTTP metadata (e.g. server IP) applies when fetching remote content.
• “Don’t show again” / “Got it”: “Got it” closes the overlay. “Don’t show again” disables it (you can re-enable it in Settings).

2.2 Help & Docs

The Help page shows documentation cards directly inside WordPress (if remote content is enabled) or links to studioplayer.de instead. A changelog may be available as well.

2.3 License & Account (Overview)

The License & Account page shows whether Pro assets are installed and whether a license is active. License management is handled via Freemius (customer dashboard/portal).

3. Muxer-Uploader (Create & Upload Audio)

The Muxer-Uploader is the starting point for your audio data: you provide stereo WAV variants and receive an optimized, multichannel streaming FLAC file (and depending on build/setup additional files such as waveform JSON).

3.1 Requirements

• You need multiple variants per track as stereo WAV files.
• Free: typically 44.1 kHz / 16-bit; Pro: may support additional high-res workflows.
• Access can be restricted depending on role/policy (e.g. Editor/Admin only).

3.2 Typical workflow

1. Open The Studio Player → Muxer-Uploader.
2. Select how many slots/variants you want (A/B or Pro: A/B/C/D if available).
3. Upload your WAV files into the slots.
4. Start the encode/mux process.
5. After completion, you will find the generated files in the Media Library (as attachments).

3.3 Common issues

• Upload fails: Check PHP upload limits, server timeouts, and disk space.
• Wrong format: Use WAV files with a compatible sample rate/bit depth.
• No permission: Role/capability may block access; an admin may need to adjust permissions.

3.4 Waveforms (Waveform JSON) – Background & Edition Limits

Waveforms are not computed “live” during playback. Instead, the plugin uses a pre-generated JSON file per track (typically the same base name as the FLAC file, but .json instead of .flac).

• What is it for? The waveform JSON enables waveform visualization in the player and avoids expensive analysis during playback.
• Free edition: Waveform JSON is generated for short tracks (up to ~20 seconds). Longer tracks are exported without waveform JSON.
• Important: Even without waveform JSON, audio playback works normally.
• Pro edition (active): Full-length waveform generation (any track length) is available with active Pro assets.
• Pro assets installed, but license inactive/expired: Depending on status, waveform generation can fall back to “short tracks only”.

4. Player-Builder (Build Playlist & Design Player)

The Player-Builder is a dedicated content type in the admin. Here you build the playlist, link the generated audio files, and define template/design.

4.1 What is a “Player-Builder” technically?

Internally, Player-Builder entries are a custom post type named thespl_playlist. They are shown in the admin but are not meant to be normal public pages.

4.2 Creating a playlist

1. Go to The Studio Player → Player-Builder.
2. Click Build New Player.
3. Add tracks and link the audio file per track from the Media Library.
4. Optional: set cover image/metadata (title, artist, variant labels, extra info).
5. Select a template (or keep the default).
6. Publish to make the player visible on the frontend.

4.3 Preview & design

• The builder loads preview assets and renders the selected template.
• If a template cannot be rendered, the builder shows a safe error message instead of causing a fatal error.

4.4 Visibility (Published vs. Draft/Private)

Frontend visibility depends on the playlist status:

• Published: public; the player can load playlist data.
• Draft/Private: only visible to users who can edit that playlist; visitors will not receive playlist data.

4.5 What you typically define in the builder

• Tracks: audio attachment per track plus title/artist/info.
• Variants: labels for A/B (or Pro: A/B/C/D) and optional per-variant notes.
• Cover: cover image per track or a default cover.
• Template: choose the player template (e.g. Default, Cover-Flow).
• Design colors: background/text/accent colors and waveform colors (used when waveform visualization is available).

5. Embedding via Shortcode

Embedding is done via the thespl_player shortcode. You can place it in pages, posts, or compatible builder elements (Shortcode block).

5.1 Standard example

[[thespl_player playlist_id="123"]]

5.2 Select a specific template

[[thespl_player playlist_id="123" template="default"]]

5.3 Alternative attribute

The attribute id is an alias for playlist_id:

[[thespl_player id="123"]]

5.4 If nothing shows up

• Missing playlist ID: Admins will see a hint with an example shortcode; visitors will see nothing.
• Playlist not published: Visitors see “Audio player currently unavailable.” (or nothing, depending on context).
• Wrong ID: Make sure the ID belongs to a Player-Builder entry.

6. Templates & Design System (Brief)

The player supports different templates. Templates consist of PHP/JS/CSS in fixed directories inside the plugin.

• Default template: Standard player layout.
• Cover-Flow: Alternative display.
• Magic Palette / Color Probe: Tools to extract a matching palette from your site and derive a design.

The exact UI controls (buttons/sliders) depend on template version and build. This draft focuses on the overall workflow.

6.1 Color Probe (scan page colors)

Color Probe helps you quickly extract colors from an existing page so the player matches your site. Typical workflow:

1. Open Player-Builder and the design/preview UI.
2. Use Color Probe to scan a target page (e.g. your homepage or a landing page).
3. Apply the detected colors as a starting point.

6.2 Magic Palette (auto-generate a palette)

Magic Palette derives a consistent palette (background/text/accent, etc.) from detected colors so the player looks cohesive. You can fine-tune the palette afterward.

7. Tools (Maintenance, Diagnostics, Pro Tools)

Under The Studio Player → Tools you will find system tools.

Tool	What it does	When to use
Sample Data	Install/remove sample content	Testing/onboarding or cleanup
Integrity Scanner	Verifies Studio Player files in the Media Library (fingerprint/file present/modifications)	Missing audio, unexpected changes, debugging
Check Streaming Routes	Additional checks for streaming routes	Intermittent streaming failures
Data Recovery Pro	Scans uploads for FLAC/JSON that are not indexed in the Media Library and re-associates them	After migration/restore, when media seems “missing”
Waveform Rebuilder Pro	Generates missing waveform JSON files for existing muxer-created FLAC audio	After upgrading to Pro or when waveforms are missing

7.1 Sample Data

Sample Data installs sample playlists and sample media so you can explore the plugin without preparing your own content. It downloads a sample package from studioplayer.de and stores it temporarily in wp-content/uploads/the-studio-player/. No site content is uploaded.

• Install Sample Data: downloads/unzips/imports the package. Afterwards you can open the playlist editor.
• Remove Sample Data: removes imported sample playlists and media (cleanup).

7.2 Integrity Scanner

Verifies Studio Player files in the Media Library and detects common issues: missing files on disk, modified files (fingerprint), and streaming route errors. The Check Streaming Routes button becomes available after the integrity run.

7.3 Data Recovery (Pro)

Scans the entire uploads directory for Studio Player files (FLAC/JSON) that are not indexed in the Media Library and re-associates them. Useful after migrations, restores, or manual file operations.

7.4 Waveform Rebuilder (Pro)

Generates missing waveform JSON files for existing muxer-created FLAC audio. This is the key step after upgrading from Free to Pro: you do not need to re-upload audio; waveforms can be generated afterwards.

• Batch processing: runs in steps and may take time on large libraries.
• Browser requirement: some tasks require Web Audio decoding support; the tool warns you if your browser cannot do it.

8. License & Upgrade to Pro

The Studio Player Free and The Studio Player Pro are separate plugins. Pro is not a toggle inside the Free plugin; it is a separate Pro plugin that you install manually. License management is handled via Freemius.

8.1 Buy Pro

1. Open the Pro page (e.g. via Get Pro in the admin): studioplayer.de/#pricing.
2. Purchase a Pro license.
3. Access the customer dashboard (Freemius) to download Pro assets and manage your license.

8.2 Install Pro (manual)

1. Download the Pro plugin ZIP from the customer dashboard.
2. WordPress → Plugins → Add New → Upload Plugin → select ZIP → Install.
3. Activate the Pro plugin.

8.3 Activate & manage your license

• Activate license: Open The Studio Player → License & Account and click Activate license (opens an activation dialog).
• License states: you may see “Free”, “Pro active”, “Pro assets present but no active license”, “Offline”, or “Account needs attention”.
• Customer portal: Manage your License opens the Freemius portal (upgrades, invoices, sites, etc.).
• Admin only: license actions may be restricted to administrators depending on role/policy.

9. FAQ & Troubleshooting

Which formats are supported?

The muxer accepts stereo WAV files (Free: 44.1 kHz / 16-bit; Pro: additionally 48 kHz / 24-bit). The output is an optimized streaming FLAC file that allows sample-accurate switching between variants.

Does it work on mobile?

Yes. Templates are responsive and touch-friendly. Streaming settings are designed for mobile networks and can be adjusted under Settings.

Why does a visitor not see a player?

• Playlist not published: Publish the Player-Builder entry.
• Wrong shortcode ID: Verify the ID belongs to a Player-Builder item.
• Caching/minify: Clear caches and test in a private/incognito window.

Why does it say “Audio player currently unavailable.”?

This typically happens when the playlist is not published or the ID does not exist. Admins may see additional debug hints.

Why do I not see a waveform?

• No waveform data for this track: the player can only draw a waveform when waveform JSON exists for that audio file.
• Free edition: waveform JSON is generated for short tracks (up to ~20 seconds). Longer tracks play normally, but do not have waveform data.
• Pro edition: full-length waveform generation (any track length) is available with active Pro assets. Use Waveform Rebuilder if waveforms are missing.
• Pro assets without active license: depending on license state, waveform generation may fall back to “short tracks only”.

How do I install/activate Pro correctly?

1. Buy Pro on studioplayer.de.
2. Download the Pro ZIP from the Freemius customer dashboard.
3. Upload and activate the ZIP in WordPress.
4. Activate/manage the license under License & Account.

What does “Sample Data” do?

Sample Data downloads a sample package from studioplayer.de, unpacks it temporarily into the uploads directory, and creates sample playlists and sample media in your Media Library. You can remove everything with Remove Sample Data.

How can I re-enable onboarding?

If you clicked “Don’t show again”, re-enable it in Settings via Onboarding Overlay.

Why do I not see embedded docs on the Help page?

If remote content is disabled (opt-out), the Help page shows links to studioplayer.de instead of embedded documentation cards. Change it in Settings under Remote onboarding & documentation.

Streaming feels slow or stutters

• Auto Detect Network: enable it to adapt to network conditions.
• Chunk/Prebuffer: fine-tune manually (Settings → Audio Config).
• Rate limiting: if enabled, ensure RPM/Burst are not too low (Range requests need headroom).

10. Settings (Detailed)

Settings are grouped into tabs. Depending on role/policy, some tabs may be restricted (e.g. security settings for admins only).

10.1 General

Setting	Meaning	Notes
Player Debug Console	Enables a debug overlay console in all players (global master switch).	Great for troubleshooting. Usually off in production.
Onboarding Overlay	Shows the onboarding overlay again.	“Don’t show again” disables it; this setting re-enables it.
Remote onboarding & documentation	Opt-in/opt-out for loading onboarding/docs/changelog/security notices from studioplayer.de.	If disabled, the admin shows website links instead.
Uninstall behavior	Controls whether wp-content/uploads/the-studio-player is deleted on uninstall.	Recommended: keep files to avoid accidental data loss.

10.2 Audio Config

Setting	Meaning	Range
Auto Detect Network	Automatically detects network conditions and adapts prebuffer/chunk settings.	On/Off
Streaming Chunk Size	Latency vs. efficiency trade-off (larger chunks reduce requests but may increase per-request payload).	Level 0–9 (~128 KiB to ~6 MiB)
Prebuffer Target (seconds)	Target buffer ahead in seconds (0 disables).	0–30 s
Continue Buffering on Pause	Continues buffering while paused (best effort; browser-dependent).	On/Off
Prefetch next tracks on sufficient buffer	Prefetches the next track when buffer ahead is sufficient.	On/Off
Ready State Ahead Threshold (seconds)	Minimum buffered-ahead seconds required to show “Ready”.	1–10 s
Variant Switch Fade	Short fade when switching variants to reduce clicks.	0–50 ms

10.3 Muxer-Uploader

Setting	Meaning	Notes
Upload Subdirectory	Optional subdirectory inside uploads/the-studio-player/audio/.	Useful for separating projects. When changed, directory protection may be applied automatically.

10.4 Security & Performance

Setting	Meaning	Range
Directory Protection (.htaccess)	Protects the audio directory using .htaccess (Apache) to reduce direct access.	On/Off
Token-based Streaming Security	Signed, time-limited streaming URLs (tokens) to reduce hotlinking.	On/Off
Token Lifetime (minutes)	How long streaming tokens remain valid.	1–1440
Rate Limiting	Limits requests per IP to protect against abuse.	On/Off
Requests per Minute	Requests/minute per IP (important for range requests).	10–1000 (recommended: 300+)
Burst Limit	Short-term burst allowance before throttling.	5–500
Show Security Verification	Controls whether a security verification box is shown in the admin.	On/Off
Plugin Access Role	Defines the minimum role/capability required to access plugin admin areas.	e.g. Admin/Editor
Global Remote Warning Banners	Allows security-critical remote warning banners on non-Studio-Player admin screens.	On/Off

11. Data, Files & Privacy

11.1 Which files does The Studio Player create?

• Audio (FLAC): muxer output for streaming (multichannel FLAC).
• Waveform (JSON): precomputed waveform data (Free: short tracks up to ~20 seconds; Pro with active assets: any track length).
• Location: typically under wp-content/uploads/the-studio-player/ (e.g. audio/).

11.2 Remote content (optional)

Remote dashboard/docs content is opt-in and can be changed anytime in Settings. Sample Data downloads a sample package from studioplayer.de; no site content is uploaded.

---

Enjoy your new tool!