README
¶
Karman – The Karaoke Manager
The Karaoke Manager Karman [ˈkaɾmɛ̃n] is a software that manages your UltraStar song library.
Motivation
Everyone who has tried to manage an UltraStar karaoke library has probably experienced how difficult it can be to ensure that all songs in the library adhere to a certain quality standard. Most libraries contain low-bitrate audio, difficult file encodings, low-res or even missing artwork, incorrectly synchronized songs and a multitude of other problems. The Karman [ˈkaɾmɛ̃n] project aims to make it easier to manage large karaoke libraries.
Karman Overview
Karman is an application running on a server that takes full control over your entire karaoke library. When using Karman you will not be moving songs into specific folders but instead you will use the import feature of the software to upload songs to the server. The software then manages the library and moves files into the right places. When you want to sing you can either sync the songs to your machine or if your network connection is fast enough you can just mount the respective folder.
In contrast to existing software (most notably the UltraStar Manager) Karman takes a few different approaches:
- Karman runs server-side and expects to be the only application or user with write access to the song library.
- Karman has the concept of a library you import songs into. Cleaning up metadata of songs and correcting common errors usually takes place on import, not at some arbitrary time.
- Karman can be easily extended to implement more complex optimizations for songs
- Karman includes a library explorer that allows (potentially unauthenticated) users to browse the library. This can be very useful when singing karaoke and people want to know which songs are available.
In the future Karman might do even more, eventually integrating a sophisticated song editor and intelligent library management
Karman Architecture
Karman is designed to be compatible with modern development and deployment strategies. At its core the Karman software consists of the Karman API Backend (in this repository). The backend provides a well-documented REST API through which clients can read data and make changes. The backend implements the song management logic and most of the import logic.
The user interface is implemented via a Web Frontend. The frontend provides the user interface of the software. It communicates with the backend exclusively via the documented REST API.
Frequently asked questions
Why is Karman a server-side application?
Karman is intended for users with huge libraries consisting of hundreds of gigabytes of songs. These kinds of libraries cannot feasibly be managed manually by a single person. There were multiple factors involved in the decision of going server side:
- Storage. Growing libraries with thousands of songs quickly exceed the free storage on typical PCs.
- Backups. By storing songs on a server it is easy to include them in periodic backups that protect your valuable songs.
- Multi user support. Large libraries often come into existence when many users merge their smaller libraries. We want to offer some kind of collaborative feature that makes it possible to work on new songs together.
- Public index. When singing it is often very useful to be able to directo users to a website where they can search their favorite songs. This would not be possible without a server.
// TODO: More questions, maybe?
Directories
¶
| Path | Synopsis |
|---|---|
|
Package api contains the HTTP endpoints of the Karman API.
|
Package api contains the HTTP endpoints of the Karman API. |
|
apierror
Package apierror provides two things: an implementation of [RFC 9457] and convenience functions that generate the errors returned by the Karman API.
|
Package apierror provides two things: an implementation of [RFC 9457] and convenience functions that generate the errors returned by the Karman API. |
|
middleware
Package middleware provides some of the middlewares used in the Karman API.
|
Package middleware provides some of the middlewares used in the Karman API. |
|
schema
Package schema contains HTTP request and response schemas used throughout the Karman API.
|
Package schema contains HTTP request and response schemas used throughout the Karman API. |
|
cmd
|
|
|
Package core is the root package for the domain logic of Karman.
|
Package core is the root package for the domain logic of Karman. |
|
Package migrations contains the database migrations of the Karman project.
|
Package migrations contains the database migrations of the Karman project. |
|
Package model contains the data models of the Karman.
|
Package model contains the data models of the Karman. |
|
pkg
|
|
|
mediatype
Package mediatype provides an implementation of [RFC 6838] media types (also known as mime types).
|
Package mediatype provides an implementation of [RFC 6838] media types (also known as mime types). |
|
nolog
Package nolog implements a slog.Handler that does nothing.
|
Package nolog implements a slog.Handler that does nothing. |
|
render
Package render implements parsing and serializing HTTP requests and responses.
|
Package render implements parsing and serializing HTTP requests and responses. |
|
render/form
Package form implements a request decoder for form data.
|
Package form implements a request decoder for form data. |
|
render/html
Package html implements a response encoder for HTML data.
|
Package html implements a response encoder for HTML data. |
|
render/json
Package json implements a request decoder and a response encoder for JSON data.
|
Package json implements a request decoder and a response encoder for JSON data. |
|
render/raw
Package raw implements a request decoder and a response encoder for raw bytes.
|
Package raw implements a request decoder and a response encoder for raw bytes. |
|
render/xml
Package xml implements a request decoder and a response necoder for XML data.
|
Package xml implements a request decoder and a response necoder for XML data. |
|
streamio
Package streamio implements utilities for working with stream data.
|
Package streamio implements utilities for working with stream data. |
|
Package task TODO: Doc: Common errors
|
Package task TODO: Doc: Common errors |
|
Package test contains utilities used for testing Karman.
|
Package test contains utilities used for testing Karman. |
|
data
Package testdata provides utility functions for filling a database with test data.
|
Package testdata provides utility functions for filling a database with test data. |
|
tools
|
|