                        AVInfo v 0.7.1


                   					    RIFFHэЗxAVI LIST
                      					LIST~"  hdrlavih
                      					LISTФ9  strlstrh  
                      					    (c) *.avi, вместо эпиграфа

 +ВСТУПЛЕНИЕ+

AVInfo предназначен для вывода информации об avi-файлах на консоль.
У программы три основных типа использования - автоматизация генерации
отчетов об avi-файлах, вывод детальной иформации об ави-файлах для
программистов, работающих с ави, и, собственно, "просто" вывод информации.

Среди того, что смотрит и выводит на экран (точнее, на stdout) программа:

* разрешение, длительность, fps
* число потоков, их тип (аудио/видео)
* тип используемых видео и аудио кодеков
* параметры звука и видео
* описание (исполнитель/копирайты/название)
* информацию о кодеке - название, автор; сайт, где его можно скачать
* битрейт, число кейфреймов для каждого потока и в сумме по потокам
* количество "потерянного" места (заголовки/junk'и/индексы)
* может генерировать списки в txt и html-формате.

 +ПРИМЕРЫ ИСПОЛЬЗОВАНИЯ+

"просто вывод" информации - avinfo movie.avi
"просто вывод для FAR'a" - edit: < avinfo movie.avi --far
"программерский вывод" - avinfo -eim movie.avi --struct-report|more
"пакетная обработка данных" (w2k/xp) 
for /r c:\anime %a in (*.avi) do @avinfo -fia7 -ees "%a" --description >>hdd_anime_list.txt


 +ТЕХНИЧЕСКАЯ ДОКУМЕНТАЦИЯ+

Использование

avinfo [-params] file.avi [--mode] [template1] [template2] 

Вместо шаблона (template1/2) можно указать "" - означает пустой шаблон и подавляет
вывод соотв. информации.

Ключи.

Ключи состоят из префикса и значений.
Префиксов в настоящий момент 2:
-f - фичи
-e - управление поведением при ошибках

-f[ixs8]

i - отключение чтения тегов (LIST-INFO)
I - включение чтения тегов
s - отключение чтения и вывода потоковой информации
S - включение чтения потоков
x - отключение чтения индекса
X - включение индекса
7 - подавление вывода на экран символов с кодами больше 128
8 - разрешение 8-битного вывода.
a - довольно сложно объяснить, что этот ключ делает. Проще отослать в sources.
	В кратце, разрешает программе "выкидывать" второстепенне ради уменьшения
	размера output. В особенности это сильно заметно для --description, вывод
    для которого "всеми силами" старается уложиться в 78 символов.

-e[imse]

m - отключение вывода сообщений об ошибках.
s - не выводить сообщение об ошибках
i - игнорировать ошибки, пытаться вывести информацию о файле не смотря на них.
	(опасно - может привести к падению программы)
e - exit @ error. выход на ошибке.

-ese приведёт к тому, что программа в случае ошибки в ави-файле просто завершится молча.

Возможные замены темплейту (устанавливают каждый из темплейтов
в зарание определенные значения)

--description  строка для descript.ion
--short  кратая строка для descript.ion
--far  вывод для фара (использовать по edit:< avinfo "!.!" --far)
--struct-report  "программистский вывод" - полная (и ненужная) информация
--list - для генерации списков (см. samples/filelist.bat)
--html, --html-css, --html-b - HTML форматирование вывода.


Немного о последних трёх темплейтах

Они генерируют отчёт в виде строки для таблицы в html документе.
--html делает "просто" таблицу, --html-css - даёт возможность использовать
для оформления css (задаются классы: avinfofilename, avinfovideo,
avinforesolution, avinfoaudio).
--html-b генерирует строчку с оформлением тегом <b> (жирный шрифт)

Для нормального использования нужно "прицепить" к полученному выводу
"шапку" - заголовок html + тег <table> и "хвост" - </table> и всё прочее.
Пример использования - samples\htmllist.bat .

Темплейты:

Темплейт немного напоминает синтаксис printf. Большая часть темплейта
просто копируется в output, кроме символов после служебных значков (#$@^).
Если подстановка распознанна - одна заменяется на соотв. значение.
Если нет - просто исчезает. Если в подстановке есть пробелы - ее следует 
помещать в кавычки (для windows)

Формат подстановки почти полностью совпадает с форматом printf:

%[flags] [width] [.precision] type

Вместо % можно использовать "более нейтральный" для командной строки ^

От стандартного printf'a его отличает только отсутствие optional prefix
(h|l|L), который в данном случае просто не нужен.

nb: (временно)  формат вывода работает только для "обычных" 
числовых параметров и не оказывает влияния на текствые/специальные поля.

Примеры подстановок:

%x     -просто значение "ширина картинки".
%0.5x  -ширина картинки 5 цифр минимум, ведущие нули
%.6x   -вывести ширину картинки длиной не менее 6 символов. 
		Дополнить слева пробелами

Программа "знает" ~ о 200 разных кодеках (с любезного разрешения владельцев сайта
http://www.fourcc.org/ их база кодеков встроенна внутрь программы).
Общее число "известных сигнатур" более 350.

Расширенная информация о кодеке выводится при помощи следующих подстановок:

%z - имя кодека
%u - урл, где можно найти кодек, доп. информацию про него
%Z - создатель кодека
%U - сайт создателя
%p - комментарий

Для аудио-кодеков:

%W - #define (из mmreg.h)
%P - имя аудио-кодека

Есть еще специальный тип подстановки:

@Xбред всякий $ еще бред #* ]

X - буква a-w (нижний регистр, латинские), каждая буква соответствует
одному из полей INFO (т.е. описания avi'шки).
Если такого поля нет, то все последующее не выводится (т.е. все, что
находится до квадратной скобки)

В самих скобках никакие подстановки прочие не действуют, кроме:

$ - собственно, значение поля
# - его "референсное" название (из стандаpта)
* - fourCC чеpыpехбайтовый код
\ - <cr>

Для данных из индекса avi-файлов (битрейта, количества кейфреймов)
существует еше один, дополнительный вид подстановки:
&AB, где A, B буквы. Полный их список с расшифровкой приведен в файле
index.

Отдельно надо сказать о двух подстановках &w и &W.
Они выводят "потерянное" место в avi-файлах. Т.е. место, занятое заголовками,
индексами, JUNK'ами, PAD'ами и прочими "не видео\аудио" данными.

Замечание по поводу размера\битрейта видео\аудио-потоков. Они считаются
"суммой" - т.е. если в файле более одного аудио-потока (например, 2 звуковые
дорожки), то будет выведена суммарная информация.

Помимо основного темплейта существует еще и темплейт для детального отчета
по каждому из потоков. Обычно он необходим или при попытке выяснить,
что именно "не так" в файле, или для детальной "инспекции" 
многопотоковых файлов. Он повторяется по отношению к каждому потоку.
Т.е. если в файле 3 потока (один видео и два звуковых), этот темплейт
будет выведен 3 раза, будучи примененным к каждому из потоков по очереди.

Полный список подстановок указан в файлах meta и info_chunk и index

Вот наиболее значимые из них:

(Заголовок AVI)

FileName            ^n (имя файла - в том виде, как передали программе, argv[1])
FileSize (exactly)  ^S (размер файла в байтах. Точно.)
FileSize (human)    ^s (Размер файла приближённо)
dwMicroSecPerFrame  ^F (время между кадрами)
dwStreams           ^t (число потоков)
dwWidth             ^x (горизонтальное разрешение)
dwHeight            ^y (вертикальное разрешение)
video codec         ^v (e.g. div3, xvid, dv50, mjpg, etc)
bits per pixel      ^B (e.g. 4, 8, 16, 24)
format tag          ^w (number) (todo - convert to text view)
Samples per second  ^D (e.g. 44100, 48000, 22050, 11025)
Chanels             ^C (e.g. 1, 2, 6)
Mono/Stereo/Number  ^c (generating from ^C e.g. Stereo, Mono, 3)

Hаиболее существенные из полей INFO:

b     Исполнитель        (IART)
e     копирайты          (ICOP)
f     дата создания      (ICRD)
k     жанр               (IGNR)
o     название           (INAM)
s     софт		         (ISFT)
r     содержимое 	     (ISBJ)

(Заголовок потоков)

fccType    $f - тип (vids/auds) - определяет - видео или аудио поток
fccHandler $h - сигнатура кодека (для видео-потока)

(Данные потока - для видео):

biBitCount              #c (число битов 4/8/16/24)
biWidth                 #w (размер картинки)
biHeight                #h

(Данные потока - для звука)

wFormatTag              #f (аудио кодек, точнее его номер)
nChannels               #H (число аудио каналов 1/2/6)
nSamplesPerSec          #p (частота - 44100/48000/11500/etc)


Наиболее существенные значения для данных индекса:

&Vn - количество ключевых кадров в видеопотоках
&ab - аудио битрейт
&vb - видеобитрейт
&am - минимальный размер фрейма
&aM - максимальный размер фрейма
&am - минимальный размер аудио-фрейма, для большинства CBR файлов он постоянен.
&b - bits per pixel (число битов на каждый пиксел видео)

 +ПРАВА, КОПИРАЙТЫ, УСЛОВИЯ РАСПРОСТРАНЕНИЯ+

Licensing:

      This program is free software; you can redistribute it and/or modify
      it under the terms of the GNU General Public License as published by
      the Free Software Foundation; any later version.

      This program is distributed in the hope that it will be useful,
      but WITHOUT ANY WARRANTY; without even the implied warranty of
      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
      GNU General Public License (copying) for more details.

      You should have received a copy of the GNU General Public License
      along with this program; if not, write to the Free Software
      Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

(c) George Shunklin 2003,  gs@shounen.ru
Home page: http://shounen.ru/soft/avinfo/
