Jukebox user manual

Jukebox turns an Android tablet into a music box for a child. The child finds songs by their pictures and plays them alone. You choose what is on the tablet, and you set the limits from a settings area behind a PIN.

How to install?

1. Jukebox needs Android 11 or later. Download the APK from the Jukebox page on the tablet.
2. Open the downloaded file. Android asks to allow installs from this source: allow it, then confirm the install.
3. Open Jukebox. On the first start it asks for access to all files: it needs this to read the library folder. Accept.
4. If the library folder does not exist yet, Jukebox creates it with a small sample, so there is something to play at once.

How to use it?

Every folder and every song is a picture tile.

• Tap a tile once: it lights up and the tablet says its name, with a sound you recorded or with the tablet's own voice.
• Tap it again: a folder opens, a song plays.
• The row of pictures at the top shows where the child is. Tap one to go back, or the home picture to go to the start.

A song plays to the end, then the next song of the same folder starts. A small bar at the bottom shows what plays, with pause, stop, previous and next. Tap the bar for the full player with a big picture and a position slider. Music keeps playing with the screen off. Videos play full screen: tap the screen for pause, the position slider and back.

The volume control in Jukebox is the app's own. It never changes the tablet's volume, and it cannot go above the maximum you set.

How to access settings?

Tap the S in the corner. The About page opens, with an Admin button. Enter the PIN. The PIN at first install is 000000: change it in the settings area. The child sees the About page too, but cannot pass the PIN.

The settings area has:

• Edit mode: long-press a tile to rename it, to hide it from the child, or to record its sounds with the tablet's microphone. A hidden tile vanishes for the child and its songs leave the playlists; nothing is deleted, and edit mode shows it dimmed. Takes are trimmed and levelled.
• Kiosk mode: the tablet stays in Jukebox. The screen is pinned, the system bars are hidden, and the Back button does nothing at the start screen. Leave it from the settings area.
• Allow videos: when off, video files are hidden.
• Maximum volume: a level the child's own volume control cannot exceed.
• Quiet hours: a daily window, for example 20:00 to 07:00, during which nothing plays and the screen shows the night. A tap on the S still opens the About page, so you can get in.
• Sleep timer: 15, 30 or 60 minutes. The screen dims over the last minute, the music fades over the last thirty seconds, then the night screen shows.
• Screen sleep: after 2, 5 or 10 minutes without a touch, the screen goes black while the music goes on. A touch wakes it.
• Tablet sleep: after 15, 30 or 60 minutes without a touch and nothing playing, the tablet turns off its screen for real, even in kiosk mode. The power button wakes it.
• Library folder and a rescan, for when you copied files by hand.
• Change PIN and Exit.

How to fill the library?

The library is the folder sadebria/jukebox on the tablet's storage (the full path is /storage/emulated/0/sadebria/jukebox). Every folder in it is a tile, and every audio or video file in a folder is a song or a video of that tile. Nest folders as you like.

You can fill it in three ways:

• From a computer on the home network, through the share described below. This is the easiest way.
• Over USB: connect the tablet to a computer and copy files into the folder.
• With a file manager on the tablet.

Jukebox plays what the tablet can decode: MP3, Ogg, Opus, FLAC, M4A, WAV and AAC for audio; MP4, MKV, WebM, AVI and MOV for video. A file the tablet cannot decode is marked on its tile and skipped.

Manage it from a computer

In the settings area, turn on "Share on the home network". The tablet then runs a small web page of its own, and shows its address and a QR code. From a computer or a phone on the same Wi-Fi, open:

http://jukebox.local:8080

The page asks for the PIN, then shows the library. There you can:

• Drop songs, videos or whole folders onto a folder to upload them. Folders keep their structure.
• Create folders, delete files and folders.
• Edit a tile: its name, its picture, whether the child sees it, and the sounds the tablet plays for it. Record them with the computer's microphone, or upload a sound file. Every take can be played, chosen or deleted.
• Change the main settings: quiet hours, maximum volume, videos allowed or not, and the sleep timer.

Every change shows on the tablet at once. Nothing leaves your home network: the page is served by the tablet itself. The share stays on while Jukebox is closed and after a restart, until you turn the switch off.

The folder format

The library is an ordinary folder tree. There is no database and no index file: Jukebox reads the folder and file names, and the layout on disk is the format. This section is the complete reference, so you can build a library by hand, on a computer, without the app.

• The root folder is /sdcard/sadebria/jukebox on the tablet (also reachable as /storage/emulated/0/sadebria/jukebox).
• When it does not exist at the first start, Jukebox creates it with a small sample. Keep it or delete it.
• Everything Jukebox adds to a folder (pictures, names, sounds) goes into one hidden folder inside it, named .sadebria-jukebox. Your own files are never renamed or changed.

The tree

Every folder is a folder tile. Every media file is a song or a video tile. Folders can be nested without limit. The root folder is the first screen the child sees.

Playing a song plays the rest of its folder after it, in folder order, and stops at the end of the folder. It does not enter sub-folders and does not start again from the top. An empty folder is still a tile: it opens on an empty screen.

Recognised extensions

Extensions are not case-sensitive. Any other file is ignored (see "What is ignored").

The extension only decides what Jukebox does with the file. Whether it plays depends on the tablet's own decoders: a file the tablet cannot decode is marked on its tile and skipped in playlists. When the setting "Allow videos" is off, video tiles are hidden and videos are left out of playlists; the files stay on disk.

Display names

The name shown on a tile comes from the file or folder name:

1. For a file, the extension is removed. A folder has no extension: Vol.1 stays Vol.1.
2. A leading run of digits, followed by one or more of space, -, _, ., ), is removed.
3. Spaces and tabs are trimmed at both ends.

A tile shows the name beside the picture, on up to four lines. The first - in a shown name starts a new line, so Octave et Melo - Le ski has the title on its own line.

A title file replaces the name without renaming the file (see "Titles"). Use it to show a child-friendly name while keeping the original file name.

Order

Inside a folder, tiles are sorted like this:

1. Folders come before songs and videos.
2. Within each group, entries whose name starts with digits come first, ordered by that number (2 - before 10 - , so no zero padding is needed; padding is fine too). A number too large for a 64-bit integer counts as no number.
3. Then the other entries of the group, in alphabetical order of their lowercased display name.

A title file changes where a song sorts, since its display name is used. It does not change where a folder sorts: a folder is sorted by its cleaned folder name.

Pictures

Pictures live in the folder's hidden .sadebria-jukebox folder, never beside the media. An image beside the media is ignored.

Folder picture

A folder's picture is cover.<img> in its hidden folder, with any image extension: cover.jpg, cover.png, cover.webp. When several exist, the first in alphabetical order wins.

Song and video picture

A song's picture is <stem>.cover.<img> in the hidden folder, where the stem is the media file's name without its extension, number prefix included:

01 - Do re mi.mp3
.sadebria-jukebox/
  01 - Do re mi.cover.jpg      the picture of that song

No picture

A tile without a picture shows a coloured square with the first letter of its name. The colour is chosen from the name, so it is stable.

Shape

Pictures are not stretched. Each folder picks one frame for all its tiles: the shape most of its children's pictures have (a tie goes to square).

A picture in the folder's frame is cropped to fill the tile. A picture in another shape is shown whole on a tinted background. For the best result, give all the pictures of one folder the same shape.

Sidecars: names and sounds

Everything Jukebox adds to a folder lives in one hidden folder in it, named .sadebria-jukebox. A sidecar is a plain file in it, named:

<prefix>.<marker>[-<n>].<ext>

The full picture:

Chansons/
  01 - Do re mi.mp3
  .sadebria-jukebox/
    cover.png                   the folder's picture
    title.txt                   the folder's display name
    entry.wav                   played when the folder is entered
    select.wav                  played when the folder tile is highlighted
    select-1.wav                an alternate take, not played
    01 - Do re mi.cover.jpg     the song's picture
    01 - Do re mi.select.wav    played when the song tile is highlighted
    01 - Do re mi.title.txt     the song's display name
    01 - Do re mi.hidden.txt    the song is hidden from the child
    hidden.txt                  the folder itself is hidden

When two files claim the same role (for example select.wav and select.mp3), the first in alphabetical order wins. A file in the hidden folder that does not match the pattern is ignored. Delete .sadebria-jukebox and the folder is back to your own files.

Folder sounds

Song and video sounds

There is no entry sound for a song: <stem>.entry.wav is ignored.

A sound plays over the music: the music dips to 20 % while the sound plays, then comes back. A sound never stops or replaces the music. A tile without a selection sound says its display name with the tablet's text-to-speech voice instead, in the tablet's language, unless the setting "Speak names" is off; a recorded sound always wins over the voice. A folder without an entry sound is silent when entered.

Keep sounds short, a few seconds. Any audio format of "The tree" works; Jukebox itself records WAV.

Titles

The title is the first non-blank line of the file, trimmed, read as UTF-8. Only the first 64 KB are read. An empty file changes nothing. A title.txt in the root's hidden folder renames the root itself, which is otherwise called "Bibliothèque" or "Library" after the tablet's language.

Hidden folders and songs

A hidden folder or song stays on disk, but the child does not see its tile, and a hidden song is never part of a playlist. The content of the file does not matter (the app writes one line, hidden). There is no numbered form: hidden-1.txt is ignored. A hidden.txt in the root's hidden folder is ignored: the root cannot hide.

On the tablet, edit mode shows hidden tiles dimmed with an eye-off badge; a long press opens the editor and its "Hidden" switch. The share page shows a "Hidden" badge on the row, and its Edit dialog has the same switch. Both write or delete this file. A rename or a delete of the media file through the share page takes the mark along, like every sidecar.

Recorded takes

The settings area of the app and the share page can record sounds. Each recording is a take, saved as 44.1 kHz mono WAV (trimmed of silence, normalised, at most 30 seconds), in the folder's hidden folder:

• When the tile has no sound of that kind yet, the take becomes the active sound: select.wav, <stem>.select.wav or entry.wav.
• Otherwise it is saved as an alternate: select-1.wav, select-2.wav, and so on, with the smallest free number.

Alternates are never played. "Use as sound" in the app swaps the active file and the chosen alternate: the old active one gets a fresh number and the chosen one takes the active name. Deleting a take deletes its file.

Alternates are only ever .wav; a title never has a number (title-1.txt is ignored).

What is ignored

Jukebox skips, without any error:

• every file or folder whose name starts with a dot, including the .sadebria-jukebox folder itself (its contents are read as sidecars; it is never a tile);
• every file with an extension not listed in "The tree" (.txt, .pdf, .m3u, .nfo, and so on);
• every image beside the media, cover.jpg included: pictures are read from the hidden folder only.

Putting the library on the tablet

Build the tree on a computer, then copy it. Three ways:

1. The share page, described in "Manage it from a computer". Drop files or whole folders on it. Folders are created as needed, names are kept, junk files (.DS_Store, Thumbs.db, desktop.ini, ._*) are skipped, and the tablet rescans by itself. An uploaded image named cover, folder or front is filed as the folder's picture sidecar, and one named like a song in that folder as the song's, so an album copied from a computer keeps its pictures. The page does not write titles: use the app's editor or write the sidecar by hand.

   The page refuses a name that contains /, \ or a NUL character, that is . or .., that starts with a dot, that has leading or trailing spaces, or that is longer than 200 characters.

2. USB or a file manager. Copy the tree into /sdcard/sadebria/jukebox, then in the settings area tap "Rescan" on the library folder row, or restart the app.
3. adb, for a developer with the tablet on USB or an emulator:

   adb push "My library/." /sdcard/sadebria/jukebox/
   adb shell am force-stop com.sadebria.jukebox
   adb shell am start -n com.sadebria.jukebox/.MainActivity

   A restart is the simplest rescan.

A .sadebria-jukebox folder travels with its folder in all three ways, including a folder dropped on the share page.

A worked example

A complete small library. Everything not marked as ignored is shown.

jukebox/                                  root; shown as "Library"
  .sadebria-jukebox/
    title.txt                             "Chez nous": the root is called "Chez nous"
  01 - Chansons/                          folder, first
    01 - Do re mi.mp3                     song, first
    02 - Frere Jacques.ogg                song, second
    03 - Au clair de la lune.mp3          song; hidden (see below), the child does not see it
    Une souris verte.mp3                  song, last (no number: alphabetical after the numbered ones)
    notes.txt                             ignored
    .sadebria-jukebox/
      cover.jpg                           the folder's picture
      select.wav                          "Chansons", spoken, when the folder is highlighted
      entry.wav                           a chime when the folder is entered
      01 - Do re mi.cover.jpg             that song's picture
      01 - Do re mi.select.wav            "Do re mi", spoken, when the song is highlighted
      02 - Frere Jacques.title.txt        "Frere Jacques (version douce)"
      03 - Au clair de la lune.hidden.txt hides that song
      select-1.wav                        an older take, not played
  02 - Histoires/                         folder, second
    Le petit ours.m4a
    Le loup et l'agneau.opus              no picture: a coloured tile with an "L"
    .sadebria-jukebox/
      cover.png                           the folder's picture
      title.txt                           "Histoires du soir"
      Le petit ours.cover.png             that story's picture
  03 - Films/                             folder, third
    Octave et Melo - Le ski.mp4           video; hidden when videos are not allowed
    cover.webp                            ignored: a picture beside the media
    .DS_Store                             ignored
    .sadebria-jukebox/
      cover.webp                          the folder's picture
  Photos/                                 folder, last; empty screen inside
    vacances.jpg                          ignored

Checklist for a library built by hand:

• One folder per folder tile, one media file per song tile.
• Number what must keep an order: 01 - , 02 - , and so on.
• A .sadebria-jukebox folder per folder with cover.jpg, and <stem>.cover.jpg for songs that deserve their own picture; one shape per folder.
• Optional, in the same folder: title.txt, select.wav, entry.wav and <stem>.select.wav, <stem>.title.txt; hidden.txt or <stem>.hidden.txt for what the child must not see yet.
• No dot at the start of a name you want shown.
• Copy into /sdcard/sadebria/jukebox, then rescan or restart.