# APlayer Integration for Navidrome Shares
This integration allows you to share music from Navidrome using APlayer, a beautiful HTML5 music player, without requiring authentication.
## Features
- 🎵 Beautiful, responsive music player interface
- 🔐 No authentication required - works with public share links
- ⏰ Respects share expiration dates
- 🎨 Clean, modern design
- 📱 Mobile-friendly
- 🔗 Easy to embed on external websites
## How to Use
### 1. Create a Share in Navidrome
1. In Navidrome, select songs, albums, or playlists you want to share
2. Click the share button and create a share link
3. Configure the share settings (expiration, description, etc.)
### 2. Get the APlayer URL
1. Go to the Navidrome admin panel
2. Navigate to "Shares" in the menu
3. Click on your share to edit it
4. You'll see two URLs:
- **Share URL**: The regular Navidrome share page
- **APlayer Embed URL**: The APlayer player page
### 3. Share or Embed
You can either:
- **Direct link**: Share the APlayer URL directly for people to listen in their browser
- **Embed in website**: Use an iframe to embed the player on your own website
#### Embed Example
```html
<iframe
src="http://your-navidrome-server/share/SHARE_ID/aplayer"
width="100%"
height="500"
frameborder="0"
allow="autoplay">
</iframe>
```
## Technical Details
### How It Works
1. The APlayer page loads the share data from the server (no authentication needed)
2. Track streaming uses JWT tokens embedded in the share link
3. Tokens automatically expire when the share expires
4. All streaming is done through Navidrome's public API endpoints
### CDN vs. Vendored Assets
**✅ Current Implementation**: APlayer assets are vendored locally and served from the application
- Files are embedded in the Navidrome binary
- No external CDN dependencies
- Works in offline/intranet environments
- Better privacy and performance
For details on the vendoring implementation, see [VENDOR_APLAYER.md](VENDOR_APLAYER.md).
### Security
- No username/password required
- Uses the same security model as regular Navidrome shares
- JWT tokens are scoped to specific shares
- Respects share expiration dates
- Cannot access data outside the shared content
### Files Added/Modified
**New Files:**
- `resources/aplayer.html` - HTML template for the APlayer page
- `resources/aplayer-share.js` - JavaScript that initializes APlayer with share data
**Modified Files:**
- `server/public/public.go` - Added route for `/share/:id/aplayer`
- `server/public/handle_shares.go` - Added handler for APlayer page
- `ui/src/utils/urls.js` - Added `shareAPlayerUrl()` function
- `ui/src/share/ShareEdit.jsx` - Added APlayer URL display
## Customization
### Styling
You can customize the appearance by modifying `resources/aplayer.html`. The default theme uses a purple gradient background, but you can change:
- Colors and gradients
- Player theme color
- Layout and spacing
- Font styles
### Player Options
Edit `resources/aplayer-share.js` to modify APlayer settings:
```javascript
const ap = new APlayer({
autoplay: false, // Auto-start playback
theme: '#b7daff', // Player color theme
loop: 'all', // Loop mode (all/one/none)
volume: 0.7, // Default volume (0-1)
// ... more options
});
```
For all available options, see [APlayer documentation](https://aplayer.js.org/).
## Credits
- [Navidrome](https://github.com/navidrome/navidrome) - Modern Music Server
- [APlayer](https://github.com/DIYgod/APlayer) - Beautiful HTML5 Music Player
- [AplayerForNavidrome](https://github.com/maytom2016/AplayerForNavidrome) - Original inspiration
## License
This integration follows the same license as Navidrome (GPL-3.0).
# Vendoring APlayer Assets (✅ COMPLETED)
The APlayer integration now uses locally vendored assets instead of CDN-hosted files. This provides better reliability, offline support, and privacy.
## Implementation Status: ✅ Complete
The following has been implemented:
1. ✅ Asset handlers created (`server/public/handle_aplayer_assets.go`)
2. ✅ Routes added for `/public/aplayer/APlayer.min.css` and `/public/aplayer/APlayer.min.js`
3. ✅ Template updated to use local assets
4. ✅ Files downloaded to `resources/` folder
## Benefits
- ✅ Works in offline/intranet environments
- ✅ No external dependencies
- ✅ Better privacy (no CDN tracking)
- ✅ Consistent versioning
- ✅ Faster load times (no external requests)
- ✅ Assets cached for 1 year for performance
## How It Works
1. APlayer CSS and JS files are stored in `resources/` directory
2. Go's embed.FS automatically embeds them into the binary
3. Public routes serve the files at `/public/aplayer/APlayer.min.css` and `/public/aplayer/APlayer.min.js`
4. The HTML template references these local URLs
5. Browser caches assets for optimal performance
## Files Involved
- `resources/APlayer.min.css` - APlayer stylesheet (12.5 KB)
- `resources/APlayer.min.js` - APlayer library (59.3 KB)
- `server/public/handle_aplayer_assets.go` - Asset serving handlers
- `server/public/public.go` - Route registration
- `resources/aplayer.html` - Template with local asset references
# APlayer Integration for Navidrome Shares
This integration allows you to share music from Navidrome using APlayer, a beautiful HTML5 music player, without requiring authentication.
## Features
- 🎵 Beautiful, responsive music player interface
- 🔐 No authentication required - works with public share links
- ⏰ Respects share expiration dates
- 🎨 Clean, modern design
- 📱 Mobile-friendly
- 🔗 Easy to embed on external websites
## How to Use
### 1. Create a Share in Navidrome
1. In Navidrome, select songs, albums, or playlists you want to share
2. Click the share button and create a share link
3. Configure the share settings (expiration, description, etc.)
### 2. Get the APlayer URL
1. Go to the Navidrome admin panel
2. Navigate to "Shares" in the menu
3. Click on your share to edit it
4. You'll see two URLs:
- **Share URL**: The regular Navidrome share page
- **APlayer Embed URL**: The APlayer player page
### 3. Share or Embed
You can either:
- **Direct link**: Share the APlayer URL directly for people to listen in their browser
- **Embed in website**: Use an iframe to embed the player on your own website
#### Embed Example
```html
<iframe
src="http://your-navidrome-server/share/SHARE_ID/aplayer"
width="100%"
height="500"
frameborder="0"
allow="autoplay">
</iframe>
```
## Technical Details
### How It Works
1. The APlayer page loads the share data from the server (no authentication needed)
2. Track streaming uses JWT tokens embedded in the share link
3. Tokens automatically expire when the share expires
4. All streaming is done through Navidrome's public API endpoints
### Security
- No username/password required
- Uses the same security model as regular Navidrome shares
- JWT tokens are scoped to specific shares
- Respects share expiration dates
- Cannot access data outside the shared content
### Files Added/Modified
**New Files:**
- `resources/aplayer.html` - HTML template for the APlayer page
- `resources/aplayer-share.js` - JavaScript that initializes APlayer with share data
**Modified Files:**
- `server/public/public.go` - Added route for `/share/:id/aplayer`
- `server/public/handle_shares.go` - Added handler for APlayer page
- `ui/src/utils/urls.js` - Added `shareAPlayerUrl()` function
- `ui/src/share/ShareEdit.jsx` - Added APlayer URL display
## Customization
### Styling
You can customize the appearance by modifying `resources/aplayer.html`. The default theme uses a purple gradient background, but you can change:
- Colors and gradients
- Player theme color
- Layout and spacing
- Font styles
### Player Options
Edit `resources/aplayer-share.js` to modify APlayer settings:
```javascript
const ap = new APlayer({
autoplay: false, // Auto-start playback
theme: '#b7daff', // Player color theme
loop: 'all', // Loop mode (all/one/none)
volume: 0.7, // Default volume (0-1)
// ... more options
});
```
For all available options, see [APlayer documentation](https://aplayer.js.org/).
## Credits
- [Navidrome](https://github.com/navidrome/navidrome) - Modern Music Server
- [APlayer](https://github.com/DIYgod/APlayer) - Beautiful HTML5 Music Player
- [AplayerForNavidrome](https://github.com/maytom2016/AplayerForNavidrome) - Original inspiration
## License
This integration follows the same license as Navidrome (GPL-3.0).
* fix(ui): improve the lyric button of the AMusic theme
* fix(amusic): update styles for music player panel SVG and disabled button states
Signed-off-by: Deluan <deluan@navidrome.org>
---------
Signed-off-by: Deluan <deluan@navidrome.org>
Co-authored-by: Deluan <deluan@navidrome.org>
Fixed issue #4787 where plugin scrobblers received an empty username during NowPlaying events. The async worker was passing context.Background() which lost all user information.
Changed nowPlayingEntry to store the full context (with cancellation removed via context.WithoutCancel) and pass it to dispatchNowPlaying. This ensures plugin scrobblers can extract username from the context for authorization checks.
Updated tests to verify username is properly propagated through the async workflow, matching the actual plugin adapter behavior of checking both request.UsernameFrom and request.UserFrom.
* fix: handle cross-library relative paths in playlists
Playlists can now reference songs in other libraries using relative paths.
Previously, relative paths like '../Songs/abc.mp3' would not resolve correctly
when pointing to files in a different library than the playlist file.
The fix resolves relative paths to absolute paths first, then checks which
library they belong to using the library regex. This allows playlists to
reference files across library boundaries while maintaining backward
compatibility with existing single-library relative paths.
Fixes#4617
* fix: enhance playlist path normalization for cross-library support
Signed-off-by: Deluan <deluan@navidrome.org>
* refactor: improve handling of relative paths in playlists for cross-library compatibility
Signed-off-by: Deluan <deluan@navidrome.org>
* fix: ensure longest library path matches first to resolve prefix conflicts in playlists
Signed-off-by: Deluan <deluan@navidrome.org>
* test: refactor tests isolation
Signed-off-by: Deluan <deluan@navidrome.org>
* fix: enhance handling of library-qualified paths and improve cross-library playlist support
Signed-off-by: Deluan <deluan@navidrome.org>
* refactor: simplify mocks
Signed-off-by: Deluan <deluan@navidrome.org>
* fix: lint
Signed-off-by: Deluan <deluan@navidrome.org>
* fix: improve path resolution for cross-library playlists and enhance error handling
Signed-off-by: Deluan <deluan@navidrome.org>
* refactor
Signed-off-by: Deluan <deluan@navidrome.org>
* refactor: remove unnecessary path validation fallback
Remove validatePathInLibrary function and its fallback logic in
resolveRelativePath. The library matcher should always find the correct
library, including the playlist's own library. If this fails, we now
return an invalid resolution instead of attempting a fallback validation.
This simplifies the code by removing redundant validation logic that
was masking test setup issues. Also fixes test mock configuration to
properly set up library paths that match folder LibraryPath values.
* refactor: consolidate path resolution logic
Collapse resolveRelativePath and resolveAbsolutePath into a unified
resolvePath function, extracting common library matching logic into a
new findInLibraries helper method.
This eliminates duplicate code (~20 lines) while maintaining clear
separation of concerns: resolvePath handles path normalization
(relative vs absolute), and findInLibraries handles library matching.
Update tests to call resolvePath directly with appropriate parameters,
maintaining full test coverage for both absolute and relative path
scenarios.
Signed-off-by: Deluan <deluan@navidrome.org>
* docs: add FindByPaths comment
Signed-off-by: Deluan <deluan@navidrome.org>
* fix: enhance Unicode normalization for path comparisons in playlists. Fixes 4663
Signed-off-by: Deluan <deluan@navidrome.org>
---------
Signed-off-by: Deluan <deluan@navidrome.org>
* ci: improve docker manifest push reliability and isolation
Split Docker manifest push into separate GHCR and Docker Hub jobs to improve pipeline reliability and resilience:
- Separated push-manifest job into push-manifest-ghcr and push-manifest-dockerhub for independent execution
- Filter tags per registry using jq to prevent cross-registry push attempts
- Add automatic retry logic (3 attempts with 30s delay) for Docker Hub push using nick-fields/retry action
- Make Docker Hub job continue-on-error to prevent Docker Hub intermittent failures from failing the entire pipeline
- Add dedicated cleanup-digests job that only requires GHCR job success
- GHCR is now the critical path and will fail the pipeline if it fails, while Docker Hub failures are tolerated with retries
This addresses the recurring 400 Bad Request errors from Docker Hub registry that were causing pipeline failures even when ghcr.io push succeeded.
* fix(ci): use ghcr.io as source for docker hub manifest creation
The docker buildx imagetools create command needs to reference the source images from where they exist (ghcr.io) rather than from Docker Hub. The digests uploaded during the build step are stored on ghcr.io, so we need to pull from there and tag to Docker Hub.
* fix(ci): simplify Docker manifest push job names for clarity
* fix(ci): add permissions for Docker manifest push jobs
* fix(ci): update permissions for GHCR manifest push to write
* fix(ci): update Docker Hub image tagging in manifest creation
* fix(ci): update permissions for GHCR manifest push to read contents and write packages
* Revert "fix(ci): update Docker Hub image tagging in manifest creation"
This reverts commit b5f04d9c8b40a9f7d9c5952e5ca57c42dadfc20a.
* feat(server): add option Lastfm.ScrobbleFirstAlbumArtistOnly to send only the first album artist
* fix: remove config parameter scrobbleFirstAlbumArtist
* test: add NowPlaying test for ScrobbleFirstArtistOnly
Add a test case for the NowPlaying function when ScrobbleFirstArtistOnly is enabled. This ensures that only the first artist from the Participants list is sent to Last.fm for both artist and album artist fields, matching the existing test coverage for the Scrobble function.
* refactor: consolidate getArtistForScrobble and getAlbumArtistForScrobble
Merge the separate getArtistForScrobble and getAlbumArtistForScrobble functions into a single parameterized function. This eliminates code duplication and makes the scrobble artist handling logic more maintainable. The function now accepts a role parameter and display name, allowing it to handle both artist and album artist extraction based on the ScrobbleFirstArtistOnly configuration.
---------
Co-authored-by: Deluan <deluan@navidrome.org>
The bulk action buttons (Make Public, Make Private, Delete) on the playlists list were displaying with poor text contrast when using dark themes like AMusic. The buttons had pinkish text (theme's primary color) on a dark red background, making them difficult to read.
This fix applies the same styling pattern used for song bulk actions by adding a makeStyles hook that sets white text color for dark themes. This ensures proper contrast between the button text and background while maintaining correct styling on light themes.
Tested on AMusic (dark) and Light themes to verify contrast improvement and backward compatibility.
Signed-off-by: Deluan <deluan@navidrome.org>
Set document.body.style.backgroundColor to match the current theme's background
color whenever the theme changes. This fixes the white background that appeared
during pull-to-refresh gestures on mobile or overscroll on desktop, where the
browser reveals the area behind the app content.
The background color is determined by the theme's palette.background.default
value if defined, otherwise falls back to Material-UI defaults (#303030 for
dark themes, #fafafa for light themes).
Signed-off-by: Deluan <deluan@navidrome.org>
Always log the configuration source at startup: shows an INFO message with the
config file path when found, or a WARN message explaining how to specify one
when not found. This helps users understand why CLI commands may fail when
run outside of systemd (where --configfile is typically specified).
Closes#4758
* feat: make Unicode handling in external API calls configurable
- Add DevPreserveUnicodeInExternalCalls config option (default: false)
- Refactor external provider to use NameForExternal() method on auxArtist
- Remove redundant Name field from auxArtist struct
- Update all external API calls (image, URL, biography, similar, top songs, MBID) to use configurable Unicode handling
- Add comprehensive tests for both Unicode-preserving and normalized behaviors
- Refactor tests to use constants and improved structure with BeforeEach blocks
Fixes issue where Spotify integration failed to find artist images for artists with Unicode characters (e.g., en dash) in their names.
Signed-off-by: Deluan <deluan@navidrome.org>
* address comments
Signed-off-by: Deluan <deluan@navidrome.org>
* avoid calling str.Clean multiple times
Signed-off-by: Deluan <deluan@navidrome.org>
* refactor: apply Unicode handling pattern to auxAlbum
Extended the configurable Unicode handling to album names, matching the
pattern already implemented for artist names. This ensures consistent behavior
when DevPreserveUnicodeInExternalCalls is enabled for both artist and album
external API calls.
Changes:
- Removed Name field from auxAlbum struct, added Name() method with Unicode logic
- Updated getAlbum, UpdateAlbumInfo, populateAlbumInfo, and AlbumImage functions
- Added comprehensive tests for album Unicode handling (preserve and normalize)
- Fixed typo in artist image test description
---------
Signed-off-by: Deluan <deluan@navidrome.org>
* Rename external auth options
ReverseProxyWhitelist was regularly confusing users that enabled it for
non-authenticating reverse proxy setups.
The new option name makes it clear that it's related to authentication, not
just reverse proxies.
* small refactor
Signed-off-by: Deluan <deluan@navidrome.org>
* add test
Signed-off-by: Deluan <deluan@navidrome.org>
---------
Signed-off-by: Deluan <deluan@navidrome.org>
Co-authored-by: Deluan Quintão <deluan@navidrome.org>
added: "quickscan", "fullscan"
updated:
- "manageUsers": `access` translates to `hozzáférés` in this context, not `elérés` (~reachableness)
- "quickscan", "fullscan", "scantype": updated to match new strings
* Signed-off-by: floatlesss <117862164+floatlesss@users.noreply.github.com>
fix(vscodedevcontainer): fix-taglib-build-issues - #4749
* Apply Gemini suggested changes
Signed-off-by: floatlesss <117862164+floatlesss@users.noreply.github.com>
* chore: install TagLib in devcontainer Dockerfile
Move TagLib installation from postCreateCommand script into the devcontainer Dockerfile to leverage Docker layer caching and simplify setup.\n\nChanges:\n- Install cross-taglib v2.1.1-1 directly in Dockerfile using TARGETARCH for multi-arch support (amd64/arm64).\n- Remove redundant libtag1-dev apt dependency; keep ffmpeg only.\n- Add CROSS_TAGLIB_VERSION as a build arg for consistency with CI/Makefile.\n- Remove postCreateCommand from devcontainer.json and delete install-taglib.sh script.\n\nWhy:\n- Avoid re-downloading TagLib on each container create; benefit from cached image layers.\n- Reduce redundancy and potential version mismatch between apt libtag and cross-taglib.\n- Keep devcontainer aligned with production build approach and CI settings.
---------
Signed-off-by: floatlesss <117862164+floatlesss@users.noreply.github.com>
Co-authored-by: Deluan <deluan@navidrome.org>
* feat: make NowPlaying dispatch asynchronous with worker pool
Implemented asynchronous NowPlaying dispatch using a queue worker pattern similar to cacheWarmer. Instead of dispatching NowPlaying updates synchronously during the HTTP request, they are now queued and processed by background workers at controlled intervals.
Key changes:
- Added nowPlayingEntry struct to represent queued entries
- Added npQueue map (keyed by playerId), npMu mutex, and npSignal channel to playTracker
- Implemented enqueueNowPlaying() to add entries to the queue
- Implemented nowPlayingWorker() that polls every 100ms, drains queue, and processes entries
- Changed NowPlaying() to queue dispatch instead of calling synchronously
- Renamed dispatchNowPlaying() to dispatchNowPlayingAsync() and updated it to use background context
Benefits:
- HTTP handlers return immediately without waiting for scrobbler responses
- Deduplication by key: rapid calls (seeking) only dispatch latest state
- Fire-and-forget: one-shot attempts with logged failures
- Backpressure-free: worker processes at its own pace
- Tests updated to use Eventually() assertions for async dispatch
Signed-off-by: Deluan <deluan@navidrome.org>
* fix(play_tracker): increase timeout duration for signal handling
Signed-off-by: Deluan <deluan@navidrome.org>
* refactor(play_tracker): simplify queue processing by directly assigning entries
Signed-off-by: Deluan <deluan@navidrome.org>
---------
Signed-off-by: Deluan <deluan@navidrome.org>
* feat: add configurable transcoding cancellation
Implemented EnableTranscodingCancellation configuration option to control whether
FFmpeg transcoding processes can be interrupted when client requests are cancelled.
This addresses resource management issues on low-power hardware where transcoding
processes would accumulate and cause CPU spikes.
Key changes:
- Added EnableTranscodingCancellation bool to configuration (default: false)
- Added CLI flag --enabletranscodingcancellation and TOML/env support
- Modified FFmpeg package to always use exec.CommandContext for consistency
- Implemented conditional context handling in NewTranscodingCache function
- When enabled: uses request context directly (allows cancellation)
- When disabled: uses background context with request metadata preserved
- Added comprehensive tests for both FFmpeg and transcoding layers
- Maintained backward compatibility with existing behavior as default
The implementation follows proper layered architecture with policy decisions
at the media streaming layer and execution utilities remaining focused on
their core responsibilities.
Signed-off-by: Deluan <deluan@navidrome.org>
* test: refactor FFmpeg context cancellation tests for improved clarity and reliability
Signed-off-by: Deluan <deluan@navidrome.org>
* test: reset FFmpeg initialization
Signed-off-by: Deluan <deluan@navidrome.org>
* test: improve FFmpeg context cancellation tests for cross-platform compatibility
Signed-off-by: Deluan <deluan@navidrome.org>
---------
Signed-off-by: Deluan <deluan@navidrome.org>
Removed the buffer.Length() check that was causing intermittent test failures.
The background goroutine started by newBufferedScrobbler can process and
dequeue scrobble entries before the test assertion runs, leading to a race
condition where the observed length is 0 instead of 1. The Eventually block
that follows already verifies the scrobble was processed correctly.
Signed-off-by: Deluan <deluan@navidrome.org>
Added a loadEnvVars parameter to InitConfig to control whether environment
variables should be loaded via viper.AutomaticEnv(). In tests, environment
variables (like ND_MUSICFOLDER) were overriding values from config test files,
causing tests to fail when these variables were set in the developer's
environment. Now tests can pass loadEnvVars=false to isolate from the
environment while production code continues to use loadEnvVars=true.
Signed-off-by: Deluan <deluan@navidrome.org>
Previously, the insights collector would only try to get an admin user once
at startup. If no admin user existed (e.g., fresh database before first user
registration), insights collection would silently fail forever.
This change moves the admin context creation inside the collection loop so it
retries on each interval. It also updates log messages in WithAdminUser to
remove the Scanner prefix since this function is now used by other components.
Signed-off-by: Deluan <deluan@navidrome.org>
