Setting Up Your SMB Server

To use Sambero, you’ll need an SMB server to host your music files. You can set this up in a few different ways: using a professional NAS, a Raspberry Pi, or by sharing folders from your Windows, Mac, or Linux computer.

If you’re new to SMB servers, don’t worry—here are some helpful guides to get you started:

• Setting up SMB on a Raspberry Pi
• Sharing folders on Mac OS
• Configuring SMB on Ubuntu

• Read-only access: Sambero only needs permission to read your files—no writing or modifications required.
• SMB 2 protocol: Ensure your server supports SMB 2, as this is required for compatibility.

If you’re having trouble connecting to your SMB share, try these steps:

• Double-check that the user account you’re using has read access to your music files.
• Test your SMB share with another app or device to confirm it’s accessible.
• A note for sharing from a windows computer: I found that you need to share from a normal account. Connecting to a Microsoft account doesn't work.

Tagging your music files

For the software to work properly, you need to add metadata to your music files by tagging them. There are many software packages that allow you to edit tags in music files. The one I'm using is MP3Tag. The following tags are recognized by the app:

• Title: Used for the title of a song. If not present, the filename is used as the title.
• Artist: The artist of a song.
• Album: The album this song is part of.
• AlbumArtist: The main artist of an album. Don't provide this tag if this is a compilation of various artists.
• TrackNr: The track number. Used to sort tracks in the album detail view by track number.
• DiscNr: The disc number. Used to sort tracks in the album detail view by disc number.
• Cover art: Used to display a cover image of the album. See Artwork for your music files for more information.
• Artist art: Used to display an image of the artist. See Artwork for your music files for more information.

All tags are optional, but it's advised to set them where appropriate. Without artist and album tags, you won't be able to browse by artist and album.

Playlists

Sambero supports playlists in M3U format, allowing you to create and enjoy custom music collections directly from your SMB share.

To ensure your playlists work smoothly:

• Save your playlists as .m3u files on your SMB share.
• Use relative paths in your M3U files, based on the location of the playlist file itself.
• Avoid using special characters like ?|<> in filenames, as they may cause issues with playback.
• Absolute paths or web URLS are not supported.

For example, if your playlist is saved in /Music/Playlists/ and references a song in /Music/Artist/Album/, the path in your M3U file should look like ../Artist/Album/song.mp3.

This keeps your playlists portable and ensures Sambero can find your music files without any hassle.

Artwork for Your Music Files

Artwork brings your music library to life, whether it's album covers, artist images, or playlist thumbnails. Sambero supports artwork stored embedded in your media files or as separate image files (PNG, JPG, or JPEG). Here's how Sambero finds and displays artwork for your music:

Sambero looks for artwork in this order:

1. If the song has embedded album artwork, that will be used.
2. If not, Sambero checks the song's directory for a file with the same name as the song, but with an artwork suffix:
   • song.mp3.album.jpg
   • song.mp3.cover.png
   • or similar (e.g., .album.png, .cover.jpg, etc.).
   For example, if your song is named Example.mp3, Sambero will look for Example.mp3.cover.png.
3. If no matching file is found, Sambero looks for generic artwork filenames in the same directory:
   • album.jpg, cover.png, etc.
4. If artwork still isn't found, Sambero checks the parent directories for generic artwork filenames.

Sambero determines album artwork by using the artwork of any song in the album that has artwork. If no songs in the album have artwork, the album will appear without artwork.

Sambero finds artist artwork in this order:

1. If the song has embedded artist artwork, that will be used.
2. If not, Sambero checks the song's directory for a file with the same name as the song, but with an artist artwork suffix:
   • song.mp3.artist.jpg
   • song.mp3.artist.png
   For example, if your song is named Example.mp3, Sambero will look for Example.mp3.artist.png.
3. If no matching file is found, Sambero looks for generic artist artwork filenames in the same directory:
   • artist.jpg, artist.png, etc.
4. If artwork still isn't found, Sambero checks the parent directories for generic artist artwork filenames.

Playlist artwork is found the same way as song artwork, but since playlists can't have embedded artwork, Sambero only looks for separate image files in the playlist's directory or parent directories.

We recommend storing artwork as separate files in your file system. Here's why:

• Easier to manage: You can update or replace artwork without editing each file.
• Faster scanning: Sambero scans your SMB share more quickly when artwork is stored separately.
• Better performance: Artwork loads faster in the Sambero interface.

Here’s an example of how you might organize your files and artwork:

                /Music/
                ├── Artist 1/
                │   ├── Album 1/
                │   │   ├── song1.mp3
                │   │   ├── song2.mp3
                │   │   ├── album.jpg          <-- Album artwork for "Album 1"
                │   │   └── song1.mp3.cover.png <-- Artwork for "song1.mp3"
                │   ├── artist.jpg             <-- Artist artwork for "Artist 1"
                │   └── Album 2/
                │       ├── song1.mp3
                │       └── cover.png          <-- Album artwork for "Album 2"
                └── Artist 2/
                    ├── song1.mp3
                    └── song1.mp3.artist.jpg  <-- Artist artwork for "song1.mp3"
                

Connecting to Your SMB Share

Ready to enjoy your music? Connecting to your SMB share is simple:

1. Go to Settings → Source in Sambero.
2. Enter your SMB share details:
   • Hostname (e.g., the IP address or network name of your NAS or computer).
   • Share name (the name of the shared folder on your SMB server).
   • Port (default is 445—you usually won’t need to change this).
   • Folder (the folder on the share to scan. To scan the whole share just leave this to the default '/' which is the root folder).
   • Username and password (the credentials for your SMB share).
3. Press the Scan button to start.

If the connection is successful, Sambero will scan your SMB share for music files. You’ll see a progress bar as it builds your library, organizing your music by artist and album using the metadata in your files.

If you add, remove, or edit files or metadata, you’ll need to scan your share again. Sambero gives you two options:

• Full scan: Scans your entire share for all files and metadata.
• Incremental scan: Only checks for changes since your last scan—faster and more efficient.

If something goes wrong during the scan, you can check the Logs (found under the Logs button) for details.

Due to AppleTV’s technical limitations, Sambero stores your music metadata in a cache on your device. This cache usually stays intact, but if your AppleTV runs low on storage, it may be cleared. If that happens, Sambero will automatically scan your share again the next time you open the app.

Licensing

This software is protected by copyright. It uses three open-source software libraries:

• libOgg, licensed under a revised BSD license.
• libFLAC, licensed under the MIT license.
• libsmb2, licensed under LGPL license. A copy of the LGPL license can be found here. According to the LGPL license your are entitled to relink the software with your own version of the libsmb2 library. To allow you to do this an XCode project is made available here. It contains a static library with the main functionality of the app. You can relink with a modified version of libsmb2 and upload it through XCode to your AppleTV. Note however, that you can only use this after you obtained the software in the appstore. And note that you can only use your modified version for personal use.

Privacy Policy

No personal data is collected through this app.

Contact Information

For comments, suggestions, or bug reports, please contact me at sambero-support@erik-online.nl.