--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/README.txt	Tue Sep 08 17:12:41 2015 +0200
@@ -0,0 +1,40 @@
+.. contents::
+
+
+Introduction
+============
+
+pyams_media is a Pyramid/PyAMS extension package used to automatically convert and
+display medias, actually audio and video files.
+
+Medias conversion is based on FFmpeg binary, which must be available on the web server.
+
+
+Medias conversions
+==================
+
+Medias conversion implies several pre-requisites:
+
+ - the ''ffmpeg'' executable must be available in your path;
+
+ - you have to rely a ZEO connection handling a blobs cache directory;
+
+ - you have to create this ZEO connection in your PyAMS control panel.
+
+A PyAMS medias converter is automatically created when pyams_package is included into your configuration
+when you execute the ''pyams_upgrade'' command line tool (see ''pyams_utils'' package).
+
+
+Conversion configuration
+========================
+
+Medias conversion is based on a specific listening process using ØMQ messages. The listening address must be defined
+in your configuration file under the key ''pyams_media.tcp_handler'', in the ''ip:port'' form. For example::
+
+    pyams_media.tcp_handler = 127.0.0.1:5556
+
+PyAMS control panel allows you to define several conversion settings, for example to define which audio and video
+formats should be available, as well as a few FFmpeg conversion settings (frame size, bitrate, sampling...).
+
+Conversion is launched automatically in the background as soon as a media file is added to any content. Converted
+medias are stored in the ZODB as blob files in the original media file annotations.