Created Format specification (markdown)

Format-specification.md

@@ -0,0 +1,71 @@
+# Template format
+
+| Variable        | Description                                                                                        |
+|-----------------|----------------------------------------------------------------------------------------------------|
+| $EXE            | Executable path replaced with format `path` attribute.                                             |
+| $OPTIONS        | Executable command-line options replaced with preset `options` attribute.                          |
+| $INFILE         | Input file path (if pipes are supported `-` is automatically used).                                |
+| $OUTFILE        | Output file path (if pipes are supported `-` is automatically used).                               |
+
+The output file name is generated from the combination of output path, item `name` attribute and output format `extension` attribute.
+
+Default template format order is `$EXE $OPTIONS $INFILE $OUTFILE`. 
+
+You can also add custom options (additional command-line parameters) and text inside the `template` string.
+
+# Type, input and output extensions
+
+BatchEncoder does support file trans-coding. To enable this you have to configure proper `Decoder` formats.
+
+BatchEncoder will chech input file extensions and if `Encoder` format `Input extensions` (multiple extension are supported,
+separated by comma `,` e.g.: WAV,WV,CAF,W64,DFF,DSF, but only one `Output extension` e.g. WV) does not match the input file extension 
+than BatchEncoder will search for `Decoder` that does support this input file extension. 
+
+# Pipes configuration
+
+Pipes configuration provides information to BatchEncoder whether the command-line tool has support 
+to read/write data from/to stdin/stdout pipes.
+
+* The input pipe means that encoder/decoder can directly read dat  from stdin and does not need input file name.
+* The output pipe means that encoder/decoder can directly write data to stdout and does not need output file name.
+* When encoder/decoder supports input pipe BatchEncoder reads file data and streams this data into encoder/decoder input pipe (stdin).
+* When encoder/decoder supports output pipe BatchEncoder writes data to a file using encoder/decoder output pipe stream (stdout).
+* Usually you can specify pipe support in command-line options by using "-" instead of input/output file name.
+
+The input pipes support allows BatchEncoder to get current progress status by counting read bytes, 
+instead of relying on console text output (this is done by reading encoder/decoder stderr pipe output). 
+
+To get console output BatchEncoder is parsing text read from stderr pipe and uses provided GetProgress function
+for specific tool. There are cases when stderr output is delayed by tool (stderr pipe buffer is not flushed)
+and resulting in progress status can be delay.
+
+Also when you want to do more complicated operations like transscoding you can for example connect pipes 
+between one encoder output (stdout) and others decoder input (stdin). This case is not yet support by BatchEncoder.
+
+The best case scenario is when encoder/decoder tool does support both input and output pipes, this gives BatchEncoder more 
+control over encoding/decoding and trans-coding processes, also in case of trans-coding you do not need temporary files 
+as data can be streamed between tools directly without temporary storage and in result you can get much better performance.
+
+Unfortunately not all command-line tools provide support for pipes, some only support stdin pipes (mainly encoders) 
+and some support only stdout pipes (mainly decoders). In this cases BatchEncoder depending on pipes input/output 
+and progress function configuration selects best possible option to do conversion process. 
+
+Sometimes you will not get nice progress during conversion, nonetheless you will successfully convert files.
+
+# Progress function format
+
+Progress function are simple [Lua](http://www.lua.org/manual/5.3/) scripts with defined `GetProgress` function. The `progress` file extension is used instead of `lua`.
+
+The progress function signature:
+
+```
+function GetProgress(s)
+```
+
+Most of the Lua progress scripts are using [string manipulation](http://www.lua.org/manual/5.3/manual.html#6.4) with [patterns](http://lua-users.org/wiki/PatternsTutorial).
+
+For a quick start use one of the [existing](https://github.com/wieslawsoltes/BatchEncoder/tree/master/progress) progress scripts.
+
+# Default progress functions
+
+The default progress functions sources can be found [here](https://github.com/wieslawsoltes/BatchEncoder/tree/master/progress).