KotlinAudioAppAdmin

This project is a desktop administration application for SymfonyAudioBackend. It synchronizes local FLAC files with the server and manages playlists, podcasts, albums, artists, genres, and background sounds.

Technologies

Area	Main technologies
Application	Kotlin 2.4.10, JVM 26, Apache Maven
User interface	Java Swing, FlatLaf for the dark appearance, MigLayout for component layouts
Background work	SwingWorker for network requests, file processing, and progress reporting
API communication	Apache HttpClient 5 and HttpCore 5; kotlinx.serialization for JSON
Media processing	FLAC Vorbis comment parsing
Logging	Kotlin Logging and SLF4J Simple
Packaging	Maven Assembly Plugin for an executable JAR containing application dependencies

Application architecture

The application is split into the following packages:

Component	Responsibility
Main.kt	Configures the appearance and opens the settings window or the main window.
gui	Provides Swing windows, feature panels, navigation, and user feedback.
worker	Runs background operations and delivers progress, results, and failures to the user interface.
service	Discovers files, calculates checksums, parses FLAC metadata, and validates form input.
service.server	Provides HTTP connectors for server availability checks and media management.
service.setting	Loads and saves local settings in config.props.
dto	Defines data transfer objects (DTOs) for settings, API requests and responses, and synchronization results.

Swing's event dispatch thread handles user interface events and updates. Background workers perform network requests and file processing, then deliver their results to this thread.

The main window provides the following functions:

Area	Functions
Synchronization	Scan a directory recursively for FLAC files and upload missing or changed songs. Show progress, a log, and a summary.
Playlists	Create, edit, and delete playlists. Browse artists, albums, and songs; add, remove, and reorder playlist entries.
Podcasts	Create, edit, and delete podcast definitions. Configure feed URLs, ignore strings, and update intervals; view update status and errors.
Albums	Browse and delete albums, edit MusicBrainz IDs, view covers, upload JPEG covers, and request image regeneration.
Artists and genres	Browse artists and genres, view covers, and request image regeneration. Delete artists together with their albums and songs.
Background sounds	Upload Opus files, browse and delete sounds, view and upload JPEG covers, and request image regeneration.

Synchronization reads FLAC metadata and calculates a checksum for each file. The server uses this information to identify unchanged, changed, or missing songs. The synchronization process can only add or update songs on the server. No files are deleted during the synchronization. Files are processed sequentially. A stop request lets the current operation finish before the run ends.

Code quality tools

The project uses the following tools for code quality and consistent formatting:

Tool	Purpose
ktlint	Kotlin formatting and style checks
detekt	Static analysis

Development and build

Building the application requires JDK 26 or newer and Apache Maven. Set JAVA_HOME to the intended JDK installation and make mvn available on PATH. Maven downloads the Kotlin compiler and other dependencies configured in pom.xml.

1. Check the Java and Maven installations:

   java -version
   mvn -version
   

2. Build the application:

   mvn clean package
   

3. Start the executable JAR:

   java -jar target/kaaa-20261018.1-jar-with-dependencies.jar
   

Running the packaged application requires Java 26 or newer with desktop support and a graphical desktop session.

The executable JAR can also be downloaded from the releases page.

Configuration and use

On the first launch, the settings window opens. Enter the backend's base HTTP or HTTPS URL in Music server URL and click Save. The application checks /rest/ping.view and expects a healthy SymfonyAudioBackend response. The backend must be reachable to complete setup.

Settings are saved under the key serverUrl in config.props in the current working directory. This directory must be writable. Launch the application from the same directory to reuse its settings. Settings can be changed through File → Settings. If a connection fails when the main window opens, choose File → Retry server connection.

In the Synchronization tab, click Start synchronization and choose a readable directory containing FLAC files. Use Stop synchronization to end a run after the current operation. The other tabs manage content stored on the server. Audio compression, podcast downloads, and image generation are handled by the backend.

AI-assisted development

This project was partially developed with AI assistance.