How to use WaxGoblin

This page walks through the Android app, then through setting up the optional Raspberry Pi touchscreen display.

1. Create your account

  1. Open the app and press Create account.
  2. Enter your email, a password (8 to 100 characters) and the same password again, then press Create account.
  3. Open the email from WaxGoblin and tap its verification link. Check your spam folder if it does not arrive; the app has a Resend email button.
  4. Go back to the app, press Continue to sign in and sign in. The app keeps you signed in until you press Sign out.

Forgot your password? Press Forgot password? on the sign-in screen and follow the link in the email.

2. Add a record

  1. Press Scan a record and allow the camera the first time.
  2. Hold the record's barcode in front of the camera. If the camera will not read it, type the digits into Barcode digits instead.
  3. The app looks the barcode up. If Discogs knows it, a form opens already filled in. If you already own it, the app shows your copy. If nothing matches, press Rescan or Enter manually.
  4. Check the form. Title and Artist are required, and so are Format, Speed and Condition. Discogs cannot always tell the format or speed (EPs especially) and never guesses the condition, so choose those yourself.
  5. Fill in the optional details if you like, then press Save record.

The optional details

FieldWhat to put
Label, Catalog numberFrom the sleeve or the record itself.
Pressing yearWhen your copy was made. Discogs fills this in.
Original release yearWhen the album first came out. You type this one. A 1997 reissue of a 1959 album has a pressing year of 1997 and an original release year of 1959. Leave it empty if you do not know.
Storage locationWhere you keep it, such as “Shelf B, row 2” or “Garage crate 3”. It is just a note for you.
Genres, NotesAdd genres one at a time. Notes are free text.

Each barcode can be saved once. Years must be between 1860 and 2100, and text fields hold up to 255 characters. The app shows a message next to anything that needs fixing.

3. View, edit or delete a record

Open a record from the search, or scan one you already own. You will see its cover, details, and (when set) First released and Stored lines.

  1. Press Edit details. The form opens with everything the record already has.
  2. Change what you like. The barcode is shown but cannot be changed, and the cover art stays as it is. To remove an optional detail, clear its box.
  3. Press Save changes. You return to the record, with “Changes saved.” Press Cancel to leave without saving.

To delete a record, press Delete from collection, then Yes, delete it. Deleting cannot be undone.

  1. Press Search collection and type. Every word must match the title, artist, label or a genre, in any order, ignoring capitals and accents (“beyonce” finds Beyoncé).
  2. Use the Decade and Genre buttons to narrow further. Press a chosen button again to clear it. A record appears under the decade it was pressed in and under the decade the album first came out in.
  3. Press a record to open it. Back returns to the search just as you left it.

5. The collection report

Press Collection report on the home screen for your total and bar charts by format, condition and genre. There are two decade charts, because a reissue was pressed in a different decade than the album first came out: By decade (pressing) counts by the year your copies were made, and By decade (release) counts by the year each album first came out.

6. Using the Pi display

The display shows your collection on a touchscreen at home. Once it is set up, it stays signed in.

The display has no PIN, so anyone who can touch the screen can edit your records (it cannot delete them). It also has no Sign out button on purpose.

7. Set up the Pi display

This is for someone comfortable with a terminal. It sets up a Raspberry Pi that boots straight into the display. The complete guide, with fixes for the problems you may hit, is display/pi/README.md in the source code.

What you need

Step by step

1. Get the code on your PC from the repository linked below, and open a terminal in its display folder.

2. Write the SD card with Raspberry Pi Imager: Raspberry Pi OS Lite (32-bit), username wax-goblin (the service files expect this exact name), your Wi-Fi details, and SSH enabled. Put the card in the Pi and power it on. Once the kiosk is running it owns the screen, so SSH is how you get a shell.

3. Install the packages on the Pi:

sudo apt update
sudo apt install -y cage chromium seatd

4. Copy and install the service files. From the display folder on your PC (replace <pi-host> with the Pi's hostname or IP address):

scp -O pi/kiosk.service pi/waxgoblin-display.service pi/99-ignore-hdmi-cec-input.rules wax-goblin@<pi-host>:~/

Then on the Pi:

sudo cp ~/kiosk.service ~/waxgoblin-display.service /etc/systemd/system/
sudo cp ~/99-ignore-hdmi-cec-input.rules /etc/udev/rules.d/
sudo systemctl daemon-reload
sudo udevadm control --reload
sudo udevadm trigger --subsystem-match=input --action=change
sudo systemctl set-default graphical.target
sudo systemctl enable waxgoblin-display kiosk

5. Build the display and copy it over. On your PC, in the display folder:

npm ci
npm run build
ssh wax-goblin@<pi-host> "mkdir -p ~/waxgoblin-display && rm -rf ~/waxgoblin-display/dist"
scp -O -r dist wax-goblin@<pi-host>:~/waxgoblin-display/

The build uses the server address in .env.production. On Windows PowerShell, use npm.cmd if npm is blocked. The -O after scp matters: without it the copy can fail with “Connection closed”.

6. Start it on the Pi:

sudo systemctl start waxgoblin-display
sudo systemctl restart kiosk.service

Within about a minute the screen shows the sign-in page (a Zero 2 W is slow).

7. Sign in once. Touch the email box, type with the on-screen keyboard, and sign in with your WaxGoblin account. The display stays signed in across reboots, and your records appear. To update the display later, repeat step 5 and restart the kiosk.

The display must be opened as exactly http://localhost:4173; the provided service files already do this. A different address is blocked by the server and the display will say it is unreachable.

8. Help, your data and the source code