Getting Started

This page covers installation, first-launch configuration, database setup, and connecting to your first streaming server. You should be up and running in under 10 minutes.

1. System Requirements

2. Installation

TagStack is currently distributed as a pre-built binary folder (no installer). An NSIS installer is planned for v2.0.

  1. Download or copy the x64\Debug\ (or Release) folder to your desired install location, e.g. C:\Program Files\Mcaster1\TagStack\.
  2. Ensure all runtime DLLs are present in the same folder as the .exe files. The required DLLs are: libcurl.dll, libssl-3-x64.dll, libcrypto-3-x64.dll, libxml2.dll, yaml.dll, iconv-2.dll, charset-1.dll, zlib1.dll, libmysql.dll, zstd.dll, tag.dll, avcodec-62.dll, avformat-62.dll, avutil-60.dll, swresample-6.dll.
  3. Double-click Mcaster1TagStack.exe to launch.

3. First Launch and YAML Configuration

On first launch, TagStack looks for tagstack.yaml in the same folder as the executable. If it does not exist, the application starts with defaults. The YAML file is created automatically when you save settings.

Minimum configuration required in tagstack.yaml:

app:
  debug-log: true
  log-file: "./logs/tagstack.log"
  log-level: "info"

database:
  host: "localhost"
  port: 3306
  name: "mcaster1_tagstack"
  user: "root"
  password: "your_mysql_password"

MySQL password in YAML: The password is stored in plain text. Restrict file system access to this file — do not place it in a public or shared folder.

4. Database Setup

TagStack requires a MySQL 8.0+ database. The schema is applied automatically via the migration system — you do not need to run SQL files manually.

  1. Start your MySQL server (mysqld or MySQL Workbench / XAMPP / WampServer).
  2. Edit tagstack.yaml and fill in the database: section with your MySQL host, port, database name, user, and password.
  3. Launch TagStack and navigate to Settings → Database.
  4. Click Initialize Schema. TagStack creates the mcaster1_tagstack database if it does not exist, then runs all 6 migration files in order.
  5. The status label shows the current schema version (should read v6 after initialization).

Tip: Use Settings → Database → Migration Wizard if you are upgrading from an earlier version. It shows which migrations are pending and lets you apply them selectively.

5. Adding Your First Server

  1. Navigate to the Servers page (top of the left nav panel).
  2. Click Add Server. The 3-step wizard opens.
  3. Step 1 — Server Type: Choose Mcaster1DNAS or Icecast2.
  4. Step 2 — Credentials: Enter the HTTPS URL (e.g. https://dnas.mcaster1.com:9443), admin username, admin password, and source password. Toggle Verify SSL off for self-signed certificates.
  5. Step 3 — Save: Give the server a friendly name and click Save. The server appears in the list.

6. Connecting to a Server

  1. Select a server in the Servers list.
  2. Click Connect. TagStack logs in via /admin/listmounts.
  3. The Select Mount dialog appears, listing all active source mounts with listener counts. Select the mount you want to push metadata to.
  4. Click OK. The player strip at the bottom turns green and displays: Connected: ServerName | Mount: /mountname.

7. Pushing Your First Metadata

  1. Navigate to ICY 2.2 Composer in the left nav.
  2. On the Station / Show tab, fill in at minimum: Station ID and Show Title.
  3. On the DJ / Track tab, fill in your DJ Handle and current track title/artist.
  4. Click Push Headers. A success/error status appears in the bottom bar.

ICY 1.x quick push: For simple "now playing" title updates, you can push directly from the Media Library page by right-clicking a track and selecting Push to Stream.

8. Setting Up the Media Library

  1. Navigate to Media Library in the left nav.
  2. Click Add Folder. A folder browser opens. Select your music folder.
  3. TagStack opens the Scan Progress dialog. In the background, it walks the folder recursively, reads audio tags via TagLib, and inserts records into MySQL. This may take a few minutes for large libraries.
  4. When the scan completes, your tracks appear in the Library tab with Title, Artist, Album, Genre, Format, Duration, BPM, and Year columns.
  5. Right-click any track → MusicBrainz Lookup to enrich the record with MBID, ISRC, label, and mood from the MusicBrainz API.

9. Launching the Media Player

The standalone Media Player (Mcaster1MediaPlayer.exe) can be launched from the command line or by double-clicking from the library:

# Play a local file
Mcaster1MediaPlayer.exe --file "C:\Music\track.mp3"

# Play an ICY stream
Mcaster1MediaPlayer.exe --stream "http://stream.example.com:8000/live"

# Play a queue of files
Mcaster1MediaPlayer.exe --playlist "C:\Music\song1.mp3" --playlist "C:\Music\song2.mp3"

10. Next Steps