trunk/man/rifftree.1.in

.TH "rifftree" "1" "7 May 2014" "libgig @VERSION@" "libgig tools"
.SH NAME
rifftree \- Print RIFF tree structure of an arbitrary RIFF file.
.SH SYNOPSIS
.B rifftree
[OPTIONS] FILE

.SH DESCRIPTION
The Resource Interchange File Format (RIFF) is a simple, binary file format
intended for tree like data structures. Many proprietary file formats are built
on top of the RIFF format (e.g. media file formats like WAV, AVI, DLS, GIG).
Data in a RIFF file is encapsulated into so called "chunks". There are list
chunks (containers) which can be seen as nodes in the data tree and thus can
have children (that is can have subchunks) and there are normal data chunks
which can be seen as leafs in the data tree and thus cannot have childs.
The regular chunks (leafs of the tree) contain the actual data to be stored.
The list chunks themselves (nodes / containers) contain no data on their own.

Each list chunk and normal chunk has a 32 bit (non unique) ID, which is usually
a four character human readable ASCII text, reflecting the purpose of the
respective list or chunk. This application will print out this ID for each chunk
found. Advantage of human readable list/chunk IDs is that files based on this
practice can easily be analyzed manually with a hex editor.

A normal RIFF file always starts with a list chunk (either with chunk ID "RIFF"
or "RIFX), which contains all other chunks. There are no other chunks outside
the boundaries of that first chunk in a normal RIFF file. You may override this
expectation with arguments described below though (see argument '--flat'), for
being able to open other, RIFF-like files.

.SH OPTIONS

.TP
.B \ FILE
Filename of the RIFF based file.

.TP
.B \ -v
Print version and exit.

.TP
.B \ -s
Print the size of each RIFF chunk.

.TP
.B \ --flat
First chunk of file is not a list (container) chunk. You might want to use this
if the file is not a "real" RIFF file. A "real" RIFF file always has a RIFF
list (container) chunk as very first chunk in a file, and it expects all chunks
to be contained in that first (list/container) chunk. So in a "real" RIFF file
there would also be no other chunks outside the scope (that is after end) of the
file's first chunk. Many primitive file formats though are a flat sequence of
ordinary data chunks (not list/container chunks). If you are using this option
then you must also use --first-chunk-id as well.

.TP
.B \ --first-chunk-id CKID
Currently only used in combination with --flat. CKID shall be the 32 bit chunk
ID of the very first chunk in the file. If the first chunk in the file does not
have the given chunk ID, then this application will abort. This ensures that
the file is actually the format you expected. The argument expected here shall
be a four character human readable ASCII text, since RIFF chunk IDs are usually
human readable ASCII strings.

.TP
.B \ --big-endian
File is in big endian format. Currently only used in combination with --flat.
Without --flat the endian type will automatically be detected. If you are using
--flat and do neither provide --big-endian nor --little-endian, then the native
endian type of your machine will be used by default.

.TP
.B \ --little-endian
File is in little endian format. Currently only used in combination with --flat.
Without --flat the endian type will automatically be detected. If you are using
--flat and do neither provide --big-endian nor --little-endian, then the native
endian type of your machine will be used by default.

.SH EXAMPLES
Show the file structure of a standard RIFF file (in the following example a
Gigasampler/GigaStudio file) and show the exact sizes of each chunk in the file:
.PP
.nf
.RS
rifftree -s piano.gig
.RE
.fi
.PP
Do the same for a Korg Trinity/Triton/OASYS/Kronos sound file (which is not a
standard RIFF file, but a RIFF-alike file):
.PP
.nf
.RS
rifftree -s --flat --first-chunk-id MSP1 --big-endian PIANO_000.KMP
.RE
.fi
.PP

.SH "SEE ALSO"
.BR dlsdump(1),
.BR gigdump(1),
.BR korgdump(1)

.SH "BUGS"
Check and report bugs at http://bugs.linuxsampler.org
.SH "Author"
Application and manual page written by Christian Schoenebeck <cuse@users.sf.net>
1	schoenebeck	2543	.TH "rifftree" "1" "7 May 2014" "libgig @VERSION@" "libgig tools"
2	schoenebeck	518	.SH NAME
3			rifftree \- Print RIFF tree structure of an arbitrary RIFF file.
4			.SH SYNOPSIS
5			.B rifftree
6	schoenebeck	2543	[OPTIONS] FILE
7
8	schoenebeck	518	.SH DESCRIPTION
9	schoenebeck	2543	The Resource Interchange File Format (RIFF) is a simple, binary file format
10			intended for tree like data structures. Many proprietary file formats are built
11			on top of the RIFF format (e.g. media file formats like WAV, AVI, DLS, GIG).
12			Data in a RIFF file is encapsulated into so called "chunks". There are list
13			chunks (containers) which can be seen as nodes in the data tree and thus can
14			have children (that is can have subchunks) and there are normal data chunks
15			which can be seen as leafs in the data tree and thus cannot have childs.
16			The regular chunks (leafs of the tree) contain the actual data to be stored.
17			The list chunks themselves (nodes / containers) contain no data on their own.
18
19			Each list chunk and normal chunk has a 32 bit (non unique) ID, which is usually
20			a four character human readable ASCII text, reflecting the purpose of the
21			respective list or chunk. This application will print out this ID for each chunk
22			found. Advantage of human readable list/chunk IDs is that files based on this
23			practice can easily be analyzed manually with a hex editor.
24
25			A normal RIFF file always starts with a list chunk (either with chunk ID "RIFF"
26			or "RIFX), which contains all other chunks. There are no other chunks outside
27			the boundaries of that first chunk in a normal RIFF file. You may override this
28			expectation with arguments described below though (see argument '--flat'), for
29			being able to open other, RIFF-like files.
30
31	schoenebeck	518	.SH OPTIONS
32	schoenebeck	2543
33	schoenebeck	518	.TP
34	schoenebeck	2543	.B \ FILE
35			Filename of the RIFF based file.
36
37	schoenebeck	518	.TP
38	schoenebeck	2543	.B \ -v
39			Print version and exit.
40
41			.TP
42	schoenebeck	518	.B \ -s
43	schoenebeck	2543	Print the size of each RIFF chunk.
44
45	schoenebeck	518	.TP
46	schoenebeck	2543	.B \ --flat
47			First chunk of file is not a list (container) chunk. You might want to use this
48			if the file is not a "real" RIFF file. A "real" RIFF file always has a RIFF
49			list (container) chunk as very first chunk in a file, and it expects all chunks
50			to be contained in that first (list/container) chunk. So in a "real" RIFF file
51			there would also be no other chunks outside the scope (that is after end) of the
52			file's first chunk. Many primitive file formats though are a flat sequence of
53			ordinary data chunks (not list/container chunks). If you are using this option
54			then you must also use --first-chunk-id as well.
55
56			.TP
57			.B \ --first-chunk-id CKID
58			Currently only used in combination with --flat. CKID shall be the 32 bit chunk
59			ID of the very first chunk in the file. If the first chunk in the file does not
60			have the given chunk ID, then this application will abort. This ensures that
61			the file is actually the format you expected. The argument expected here shall
62			be a four character human readable ASCII text, since RIFF chunk IDs are usually
63			human readable ASCII strings.
64
65			.TP
66			.B \ --big-endian
67			File is in big endian format. Currently only used in combination with --flat.
68			Without --flat the endian type will automatically be detected. If you are using
69			--flat and do neither provide --big-endian nor --little-endian, then the native
70			endian type of your machine will be used by default.
71
72			.TP
73			.B \ --little-endian
74			File is in little endian format. Currently only used in combination with --flat.
75			Without --flat the endian type will automatically be detected. If you are using
76			--flat and do neither provide --big-endian nor --little-endian, then the native
77			endian type of your machine will be used by default.
78
79			.SH EXAMPLES
80			Show the file structure of a standard RIFF file (in the following example a
81			Gigasampler/GigaStudio file) and show the exact sizes of each chunk in the file:
82			.PP
83			.nf
84			.RS
85			rifftree -s piano.gig
86			.RE
87			.fi
88			.PP
89			Do the same for a Korg Trinity/Triton/OASYS/Kronos sound file (which is not a
90			standard RIFF file, but a RIFF-alike file):
91			.PP
92			.nf
93			.RS
94			rifftree -s --flat --first-chunk-id MSP1 --big-endian PIANO_000.KMP
95			.RE
96			.fi
97			.PP
98
99	schoenebeck	518	.SH "SEE ALSO"
100	schoenebeck	2543	.BR dlsdump(1),
101	schoenebeck	2778	.BR gigdump(1),
102			.BR korgdump(1)
103	schoenebeck	2543
104	schoenebeck	518	.SH "BUGS"
105	schoenebeck	2778	Check and report bugs at http://bugs.linuxsampler.org
106	schoenebeck	518	.SH "Author"
107	schoenebeck	2778	Application and manual page written by Christian Schoenebeck <cuse@users.sf.net>