diff --git a/README.md b/README.md
index a0e49d4..d0f7965 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,249 @@
-## TODO: this file
\ No newline at end of file
+
+ A highly configurable showcaser for active media players.
+
+
+**[Installation](#installation) | [Configuration](#configuration)**
+
+This script allows you to showcase information about the active mpris media player in any Polybar configuration.
+
+
+
+## Table of Contents
+
+* [Introduction](#introduction)
+* [Installation](#installation)
+* [Customization](#customization)
+* [Defaults](#defaults)
+* [Documentation](#documentation)
+* [License](#license)
+
+## Introduction
+
+This script allows one to show the currently actoive media player. It has a variety of configuration options - handled through one or more config files - that allow one to customize the output to their liking. The script makes use of MPRIS media player identities, and only accepts these as valid players.
+
+
+
+## Installation
+
+Installing the script is straightforward; simply download the appropriate executable from the releases tab, and place it somewhere easily remembered - personally I like to keep all my polybar scripts in ~/.config/polybar/scripts.
+
+To use the script, use the following module in your polybar config:
+```
+[module/now-playing]
+type = custom/script
+tail = true
+format =
+exec = ~/.config/polybar/scripts/polybar-now-playing-rust
+click-left = "kill -USR1 $(pgrep --oldest --parent %pid%)"
+click-right = "kill -USR1 $(pgrep --oldest --parent %pid%)"
+```
+
+In this case, either left- or right-clicking on the script will pause the displayed media player, but these lines are optional and may be left out.
+
+### Building from source
+
+Thanks to Rust, building from source is easy as well. To do so, simply download this repo and then run "cargo build --release"
+
+```
+git clone github.com/djairoh/polybar-now-playing-script
+cd polybar-now-playing
+cargo build --release
+```
+
+When the build process finishes, the executable file may be found at target/release/polybar-now-playing-rust[.exe]
+
+
+## Customization
+The main strength of this project lies in its' veritable customization. There are a few flags available when running the script, but most of the customization is reached through use of configuration files.
+
+### CLI arguments
+When calling the script with the flag `--help`, the following is printed:
+```
+Program which finds the active mpris player and displays metadata about the playing piece of media.
+
+This program is intended to be used with polybar. As such, most configuration is done through config files.
+
+Usage: polybar-now-playing-rust [OPTIONS]
+
+Options:
+ -c, --config
+ The name of the config file to use
+
+ [default: default]
+
+ -l, --list
+ Enable list mode.
+
+ This mode prints all active players to stdout, to allow one to find the appropriate player names to use in the config files.
+
+ --log
+ Set log level.
+
+ Sets the log level to print to stdout.
+
+ [default: error]
+ [possible values: trace, debug, info, warn, error]
+
+ -h, --help
+ Print help (see a summary with '-h')
+```
+
+### Config files
+Much more interesting, of course, are the various options available in the configuration files. Below is detailed a full example of a config file, complete with annotations explaining each value.
+
+
+ All available options and succint explanations
+
+ ```toml
+# hides the last output if there is currently no active player
+# boolean
+hide_output = true
+# applies an extra function to fields whose output exceeds num_chars. The function will try to truncate the string at the nearest whitespace character before num_chars
+# boolean
+fuzzy = false
+# whether to display the prefix characters in the output string at all
+# boolean
+render_prefix = true
+
+# time taken between updates of the output string, in milliseconds
+# u64 (0 <= u64 <= 18446744073709551615)
+update_delay = 300
+
+# what string to use between metadata fields
+# string
+metadata_separator = ' | '
+# what character to use to separate values in an array (ie mediafile with multiple artist metadata entries)
+# char
+array_separator = '+'
+# what character to insert when a field is truncated
+# char; optional
+break_character = '-'
+
+
+# What mpris identities to consider for output. Players not in this map will never be used. Values closer to 0 are considered higher priority.
+# Note that each string should be paired with an unique u8; if this is not the case, one of the duplicates will be chosen at random during startup and all others discarded (undefined behaviour).
+# Similarly, each key should occur at most once.
+# HashMap where u8: 0 <= u8 <= 255
+[player_priorities]
+Clementine = 1
+Spotify = 2
+mpv = 3
+"VLC Media Player" = 4
+Firefox = 5
+Chromium = 6
+
+
+# what icons to use for the xesam:userRating field.
+# if left blank and the xesam:userRating field is enabled, default values will be used.
+# char, char, char; optional
+[rating_icons]
+nil = '-'
+half = '/'
+full = '+'
+
+
+# The following represent metadata_fields to include in the output. To add new entries, use the following format:
+# [[metadata_fields]]
+# field = ''
+# num_chars =
+# See https://www.freedesktop.org/wiki/Specifications/mpris-spec/metadata/ for available fields.
+# string, u8 (0 <= u8 <= 255)
+[[metadata_fields]]
+field = 'xesam:title'
+num_chars = 40
+
+[[metadata_fields]]
+field = 'xesam:artist'
+num_chars = 20
+
+
+# The prefixes to use with various players. Each entry is keyed by the Mpris identity.
+# This map should contain an entry with the "default" key - although one is hard-coded to be used if it is absent. Leaving the map empty results in all players being rendered with the hard-coded default value ('>').
+# If you don't want the program to use prefixes at all, set the render_prefix option earlier in this config to 'false'.
+# HashMap
+[player_prefixes]
+chromium = 'g'
+Clementine = 'c'
+default = '>'
+Firefox = 'f'
+mpv = 'm'
+Spotify = 's'
+"VLC Media Player" = 'v'
+ ```
+
+
+## Defaults
+Whenever a config file is specified that does not actually exist, the script creates a new file and populates it with some default values. For posterity, these defaults are included below.
+
+
+ Default configuration file
+
+ ```toml
+ hide_output = true
+ fuzzy = false
+ render_prefix = true
+ update_delay = 300
+ metadata_separator = ' | '
+ array_separator = '+'
+ break_character = '-'
+
+ [player_priorities]
+ mpv = 3
+ Firefox = 5
+ Chromium = 6
+ Clementine = 1
+ Spotify = 2
+ "VLC Media Player" = 4
+
+ [rating_icons]
+ nil = '-'
+ half = '/'
+ full = '+'
+
+ [[metadata_fields]]
+ field = 'xesam:title'
+ num_chars = 40
+
+ [[metadata_fields]]
+ field = 'xesam:artist'
+ num_chars = 20
+
+ [player_prefixes]
+ Firefox = 'f'
+ mpv = 'm'
+ Spotify = 's'
+ chromium = 'g'
+ Clementine = 'c'
+ default = '>'
+ "VLC Media Player" = 'v'
+ ```
+
+
+
+## Documentation
+All code in this repository is documented using Rustdoc. The documentation can be compiled and viewed by entering the command `cargo doc --open` while in the base directory.
+
+## License
+This script is licensed under the GPL-3.0 license. [see LICENSE for further explanation](https://github.com/djairoh/polybar-now-playing-script/blob/main/LICENSE)
\ No newline at end of file