Running, part I, II, III

README

@@ -43,9 +43,77 @@ Optional:
 ==================
 Using the software
 ------------------
+
 Configuration:
+--------------
 Please read doc/config before anything else.
 
+Preparing data:
+---------------
+Nothing specific needs to be done. You can edit ypur tags, rename files, move
+them around how you see fit. However, make sure you setup your tag editor
+to *do* update the files' timestamps: though it was initially plan to make this
+optional, using checksums or tags, it was abandoned due to the huge amount of
+IO required.
+
+Running:
+--------
+Make sure your configuration is correct by running 
+$ atom -C
+This will produce a human-readable dump of your current configuration.
+If all settings are correct, simply run atom with no argument. Go get a beer.
+Meet some friends. Go to bed. Depending on the size of your collection, the
+first run can take hours, even days.
+After adding/tagging/renaming/deleting files, just re-run atom. It should be
+much faster this time, as only changed data will be treated.
+
+If, for whatever reason, you need to force the regeneration of a destination,
+after changing the quality settings for example, run
+$ atom -F <destination name>
+
+=================
+Technical details
+-----------------
+I. Source scan
+--------------
+After reading its configuration file, AtOM uses find to get a list of all files
+in the source directory.
+Each file is checked against the database. If it's already there, and its last
+modification time is unchanged, the last_seen field is updated, and that's all.
+If its mtime has changed, mime-type scan is attempted. It is updated in the
+database, along with last_seen.
+If the file is new, its mime-type is scanned, and it is added to the database.
+
+II. Obsolete files
+------------------
+Using the last_seen field, AtOM removes from destinations each files which are
+not present anymore in the source directory. AtOM never touches files not
+present in its database (unless there is a filename conflict, in which case your
+file *WILL* be overwritten). If you wish to clear unknown files from your
+destinations, have a look at toys/cleandestinations.
+
+III. Reading metadata
+---------------------
+AtOM then tries to read metadata from each new or changed file. It also re-reads
+metadata from files scanned with an older version of AtOM, if the parser for
+that format has changed. The actual data read depends on the format, but at the
+very least, AtOM should identify the sampling rate, bitrate and number of
+channels. Unknown file types are scanned with ffprobe, so you may still have
+some luck, depending on your FFmpeg setup.
+
+IV. Task creation
+-----------------
+
+V. Transcoding
+--------------
+
+VI. Copies
+----------
+
+VII. Obsolete files 2
+-------------------
+
+
 ====
 Toys
 ----