splinge

FLAC Builder

Splinge FLAC Master Builder
User Documentation

App: FLAC Master Builder — flacBuilderCpp · Type: local desktop application (not a website) Version: August 2026

This document covers flacBuilderCpp, the C++/Qt6 build of the FLAC Master Builder desktop tool. It is a 1:1 port of the original Java flacBuilder app and produces identical output — pick either build, whichever runs more easily on your machine. For listing and selling the resulting music, see Splinge Record Store Manager — User Documentation.

1. What Is FLAC Master Builder?

FLAC Master Builder is a small local desktop app. You give it one or more audio files, put them in track order, title each one, and it builds a single master FLAC file with an embedded CUESHEET tag — the same format the Record Store's own server-side build produces (api/fileAPI/src/worker.js).

Drop that .flac into Record Store Manager's Audio File upload step and it automatically splits back into the individual tracks it was built from, exactly as if the master had been assembled by the web app.

The app runs entirely on your computer. It does not sign in, create or edit a listing, or talk to any Splinge API — it only writes a file to a folder you choose.

flacBuilderCpp is the C++/Qt6 version. There is also a Java version (flacBuilder) that behaves identically; the two are interchangeable and their output is byte-compatible.

2. Do You Actually Need It?

Usually no. Record Store Manager already builds masters for you: on a Digital listing, once at least two tracks each have their own uploaded audio, a Build master FLAC button runs the same job as a background task.

Use this desktop tool when you want to prepare the master outside the browser — for example:

  • You have a large number of tracks and prefer to assemble the master once locally rather than upload each track and wait for the in-browser pipeline.

  • You want a master FLAC (and a cue sheet) as a deliverable in its own right, independent of any listing.

  • The in-browser build is failing and you want a known-good file to upload directly.

3. Prerequisites

To run the app:

  • A Qt6 runtime (the Widgets module) — installed automatically as a dependency when you install the build packages below.

  • ffmpeg and ffprobe on your PATH. The app shells out to the system binaries; it does not bundle a copy. Install from ffmpeg.org or via your package manager (apt, Homebrew brew, Chocolatey choco). The app checks for both at startup and disables the build button with an error dialog if either is missing.

To build the app from source:

  • CMake 3.16 or newer

  • A C++17 compiler

  • Qt6 development headers (Widgets)

On Debian/Ubuntu:

sudo apt install qt6-base-dev cmake build-essential

4. Building the App

From the flacBuilderCpp/ directory:

/build.sh

This runs CMake in Release mode and compiles with all cores. The result is the executable build/flacBuilder.

5. Running the App

./build/flacBuilder

The main window opens immediately. If ffmpeg or ffprobe can't be found on your PATH, you'll get an "ffmpeg not found" dialog on launch and the Build Master FLAC button stays disabled — install ffmpeg and restart.

6. The Window, Field by Field

Element

What it does

Album name

Text field at the top. Required. Used to name the output files (see §8).

Track table

Three columns: # (track number, auto), File (source filename, read-only), Title (editable — double-click the cell). Single-row selection.

Add Files…

Opens a file picker (multi-select). Each file chosen is appended as a new track. There is no file-type filter — pick audio files only.

Remove

Deletes the selected row from the track list.

Move Up / Move Down

Reorders the selected track. Track numbers and the eventual cue-sheet order follow the table order.

Output folder

Read-only field showing where the master will be written. Defaults to your home folder. Change it with Browse… (you can't type a path directly).

Browse…

Choose the output folder.

Progress bar

0–100% during a build.

Status line

Text below the progress bar — current file being converted, then "Encoding master…", then the final output path or an error.

Build Master FLAC

Starts the build. Disabled while a build is running and while ffmpeg is missing.

When you add a file, its Title defaults to the filename with the extension stripped. Edit it before building — the title is what ends up in the cue sheet (and therefore the track name shown in Record Store Manager).

7. Building a Master FLAC — Step by Step

  1. Enter an album name. Required — the build refuses to start without one.

  2. Add Files… and select your track audio. Repeat to add more.

  3. Order the tracks with Move Up / Move Down.

  4. Set each Title by double-clicking the Title cell.

  5. Browse… to an output folder (or leave it at your home folder).

  6. Click Build Master FLAC.

The build runs in the background — the window stays responsive and the progress bar and status line update as it goes. Roughly:

  • 0–60% — converting each input to FLAC one at a time

  • ~65% — encoding the combined master

  • ~95–100% — writing the output files

On success you get a "Build complete" dialog with the full path to the master. On failure you get an "Error" dialog with the ffmpeg message; nothing partial is left in the output folder except possibly an overwritten file (see §11).

You can't cancel a running build from the UI — quit the app to abort.

8. What Gets Written

Both files land in the output folder. Their base name is the album name sanitised: every character that isn't a letter, digit, _, or - becomes _; an empty result becomes album.

File

Purpose

<album>.flac

The master. A single FLAC containing every track concatenated, with the cue sheet embedded as a CUESHEET metadata tag. This is the file you upload.

<album>.cue

A plain-text sidecar copy of the same cue sheet, for your reference / inspection only. Record Store Manager ignores it — it reads only the tag embedded in the .flac.

If a file of the same name already exists in that folder, it is overwritten without warning.

9. Using the Master in Record Store Manager

  1. In Record Store Manager, create or edit a Digital listing and go to the Audio File step.

  2. Upload the <album>.flac this app produced.

  3. It's detected as a FLAC with an embedded cue sheet and split automatically into one track per cue entry, using your titles.

  4. Continue through the wizard (Track List, Personnel, Cover Art, Pricing) as normal.

You do not need to run Record Store Manager's own Build master FLAC step afterwards — the file you uploaded already is one.

10. How It Works Under the Hood

For the curious. The app mirrors the server-side media worker (api/fileAPI/src/worker.js) minus the download/upload stages, so output is identical:

  1. Convert each input to FLAC in a temp directory (ffmpeg -i … -c:a flac).

  2. Probe each converted file's exact duration with ffprobe.

  3. Compute cumulative start times — track n starts at the sum of durations 0…n-1.

  4. Generate the cue sheet (FILE … / TRACK nn AUDIO / TITLE / INDEX 01 mm:ss:ff), using 75 CD frames per second, byte-for-byte compatible with api/fileAPI/src/services/cueSheet.js.

  5. Concatenate all the per-track FLACs with ffmpeg -filter_complex "…concat=n=N:v=0:a=1…" — a full decode + re-encode (-c:a flac -compression_level 0), never a raw stream copy. Each input FLAC has its own STREAMINFO header, so a stream-copy concat would silently truncate the master's reported duration to just the first track.

  6. Embed the cue sheet as -metadata CUESHEET=… and copy the result to your output folder, alongside the .cue sidecar.

11. Known Limitations

  • No cancel button. A running build can only be stopped by quitting the app.

  • Existing output files are overwritten silently if the album name (sanitised) collides with a file already in the output folder.

  • The output folder field is read-only — you must use Browse…, you can't paste or type a path.

  • No file-type filter in the Add Files dialog. If you add a non-audio file, the build fails partway through with a raw ffmpeg error rather than being caught up front.

  • No minimum track count. The app will happily build a "master" from a single track. Record Store Manager's own in-app build requires two or more; this tool doesn't enforce that.

  • Album name is sanitised for the filename only. Track Titles are written into the cue sheet exactly as typed (including quotes and punctuation) — check them before building.

  • FLAC inputs are still fully re-encoded. This is deliberate (see §10, step 5), not a bug — but it means the master is not a lossless passthrough of an already-FLAC source, it's a lossless re-encode.

  • -compression_level 0 (matching the server) favours encode speed over file size — the master is larger than a default-compression FLAC would be.

12. Tips & Troubleshooting

The Build button is greyed out

Either you haven't got ffmpeg/ffprobe on your PATH (you'd have seen a dialog on launch — install ffmpeg and restart), or a build is already running.

"ffmpeg not found" on startup

Install ffmpeg (which includes ffprobe) and make sure both are on your PATH, then relaunch. Test with ffmpeg -version and ffprobe -version in the same terminal you start the app from.

The build fails with an ffmpeg error partway through

Usually one of the input files isn't decodable audio — a mislabelled file, a corrupt download, or something that isn't audio at all. Remove it and try again. The status line and the error dialog show the tail of ffmpeg's output.

"Album name required" / "No tracks"

Enter an album name and add at least one file before clicking Build.

Record Store Manager didn't split my upload into tracks

Make sure you uploaded the .flac, not the .cue. Only the FLAC carries the embedded cue sheet that triggers auto-split; the .cue sidecar is reference-only.

The track titles in Record Store Manager are wrong

They come from the Title column at build time. Fix the titles in the app and rebuild — or edit them per-track in Record Store Manager's Track List step after upload.

I want the exact same output as the website

You already have it — this app runs the same steps as api/fileAPI/src/worker.js. The Java flacBuilder build is equivalent too.

Splinge FLAC Master Builder (C++/Qt6) · User Documentation · August 2026.