From 3b42ac5d7778d6605ba161b987e63405948c8393 Mon Sep 17 00:00:00 2001
From: Pavel 'LEdoian' Turinsky <ledoian@matfyz.cz>
Date: Thu, 8 Jul 2021 07:17:52 +0200
Subject: [PATCH] Add readme containing documentation.

WIP: The example config file is not there, nor is screenshot.
---
 README.md | 114 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 114 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..64a780a
--- /dev/null
+++ b/README.md
@@ -0,0 +1,114 @@
+QuickPlay
+===
+
+A simple Xamarin.Android app to allow fast playing of songs on remote players
+like MPD. Supports all Android versions since KitKat (to repurpose an old tablet).
+
+Setup of additional services
+===
+
+Since QuickPlay is only a frontend to MPD running somewhere, and the location
+has to be specified in the player configuration (see below).
+
+Currently, only unauthenticated MPD connections specified by IP address are supported.
+
+Usage
+===
+
+First, make sure that you have the player configuration INI file. Put that on
+the magic URL: <http://www.ms.mff.cuni.cz/~turinskp/znelky.ini>. Now run the
+app, your songs will appear and you can play them.
+
+An example commented INI file is provided: `playerconfig.ini`. This is what you
+would see if you use that:
+
+![UI example](./uiexample.png)
+
+Architecture Overview
+===
+
+The app comprises of three main parts:
+
+- Configuration
+- Player -- the backend
+- Layout -- the frontend
+
+Configuration
+---
+
+The configuration is split into two parts: Applocation configuration and player
+configuration.
+
+Application configuration is local to the device and describes application
+behaviour and where to obtain the player configuration. It
+is just a XML-serializable class (for simplicity).
+
+Player configuration is stored on an HTTP server or local filesystem. It is an
+INI-like file designed to be written by hand. Since INI is not a well-specified
+format, the specific format used in QuickPlay is described in `IniParser.cs`
+file. (It was faster to implement own format than to find a usable one on
+NuGet.) For use as a player configuration, the section `[general]` has to be
+specified with connection details, other sections directly describe individual
+songs.
+
+The motivation for the split is to make player configuration easily shareable,
+e.g. by a QR code pointing to the config.
+
+Currently, there is no application configuration and the player configuration
+is always downloaded from <http://www.ms.mff.cuni.cz/~turinskp/znelky.ini>,
+
+Players
+---
+
+QuickPlay is designed to support other players, not just MPD. Therefore, a
+`Player` is just an interface that can play Playables and export some trivial
+state.
+
+A `Playable` is an abstract object that can be played. Usually it is a song
+(description thereof), but there is a possibility it could be for example a
+playlist. (In the extreme case that someone would like to play chess instead of
+songs, the individual chess pieces would be playables.)
+
+In order to allow players to show current state, `MainActivity` has method
+`OnPlayerUpdate`, which re-fetches player state and displays it.
+
+It is expected that the players will maintain a service to monitor the remote
+state. It is not required though, it is really implementation detail of the
+client. (`MainActivity.OnPlayerUpdate` still has to be run on UI thread.)
+
+### MpdPlayer details
+
+The MpdPlayer is just a thin wrapper around [slightly
+patched](https://github.com/LEdoian/mpcCore)
+[mpcCore](https://github.com/svanelten/mpcCore) library. It currently only
+sends commands to the MPD, but extension by service to monitor it is ready
+(`MpdMonitorService.cs`).
+
+
+Frontend
+---
+
+Frontend is just a bunch of boilerplate code to power the RecyclerView behind
+it. The only "original" part are layout strategies -- objects that determine in
+what order the playables will be shown, based on their metadata.
+
+
+Planned Features
+====
+
+- [ ] Working application configuration
+- [ ] Player configuration sharing via QR codes
+- [ ] Showing current song progress
+- [ ] Possibility to stop current song
+- [ ] MPD player monitoring service
+- [ ] Time-based layout strategy
+
+Bugs
+---
+
+- [ ] The MpcCore client seems to disconnect after some time for no apparent reason.
+
+The far future
+---
+- [ ] Editing the player config right on the device (with INI file export)
+- [ ] Tests. (The code should be testable, but no tests has been written yet.)