diff --git a/README.md b/README.md
new file mode 100644
index 0000000..7dac57a
--- /dev/null
+++ b/README.md
@@ -0,0 +1,16 @@
+# video feed prototypes
+
+These scripts poll a peertube instance to return a list of videos and construct a static page for it using jinja2.
+
+## video-feed.py
+
+Returns the latest six local videos.
+
+## streams-feed.py 
+
+Returns only livestreams and displays them differently depending on the tags associated with the video. E.g. audio stream or video stream. WIP.
+
+## video-feed-prototype.html
+The jinja template.
+
+