diff --git a/README.md b/README.md
index ecb2b58..4f05bcc 100644
--- a/README.md
+++ b/README.md
@@ -1,11 +1,58 @@
 Negro Mate Songs
 ================
-NegroMate's song database library.
+[Negro Mate](https://negromate.rocks)'s song database library. Not very versatile without two another packages:
 
-Install from source
--------------------
-Instalation uses the pep517 packaging format, whichs requires pip version
-19 or newer.
+ * [negromate.web](https://pypi.org/project/negromate.web/): Static html compiler for the web of Negro Mage
+ * [negromate.karaoke](https://pypi.org/project/negromate.karaoke/): Simple karaoke video browser
 
-    pip install "pip>=19"
-    pip install .
+Provides the base `negromate` command to interact with a song repository.
+
+    negromate config: Write the configuration file
+    negromate songs: Update song database
+    negromate thumbnail: Generate cover and thumbnail for a song
+
+Needs the following packages installed:
+
+ * imagemagick
+ * ffmpeg
+
+Karaoke subtitle generation is currently broken, it worked with these
+packages on older systems:
+
+ * xdotool
+ * aegisub
+ * xserver-xephyr
+
+
+## Song library structure
+
+Each song is a folder containing at least a video file, a subtitles file and a metadata file:
+
+    song_name/
+    ├── song_name.ass
+    ├── song_name.mp4
+    └── metadata.json
+
+Video and subtitles file has to be named like the folder. Supported subtitles:
+
+ * ass (prefered)
+ * src
+ * vtt
+
+### The metadata json file
+
+    {
+        "name": "Song name",
+        "original": "Original song, Original author",
+        "karaoke": true,
+        "date": "XXXX-XX-XX"
+        "author": "Author of the karaoke"
+    }
+
+
+* `name`: used as the title of the song.
+* `original`: for giving credit to original authors.
+* `karaoke`: if `true`, the ass subtitles file has karaoke level subtitles (syllable level timing)
+  and automatik karaoke subtitles can be generated.
+* `date`: approx. creation date of this version
+* `author`: not required, used for givin credits to the author when it's different from the web authors.
diff --git a/requirements.txt b/requirements.txt
index 778f2b0..1d2a9c8 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -1,3 +1,4 @@
-webvtt-py
+ass==0.5.2
+webvtt-py==0.4.6
 asstosrt==0.1.6
 srt==3.5.3
diff --git a/setup.cfg b/setup.cfg
index 884d8f4..f15b90d 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -6,10 +6,10 @@ version = attr: negromate.songs.VERSION
 license-file = LICENSE.txt
 author = Ales (Shagi) Zabala Alava
 author_email = shagi@gisa-elkartea.org
-url = http://negromate.rocks
+url = https://negromate.rocks
 description = NegroMate karaoke song database library
 long_description_content_type = text/markdown
-long_description = files: README.md, CHANGELOG.md
+long_description = file: README.md, CHANGELOG.md
 license = GPLv3
 classifiers =
     Development Status :: 5 - Production/Stable
@@ -26,6 +26,7 @@ install_requires =
     webvtt-py
     asstosrt ==0.1.6
     srt  ==3.5.3
+    ass  ==0.5.2
 
 [options.entry_points]
 console_scripts =