X-Git-Url: http://git.tuebingen.mpg.de/?p=paraslash.git;a=blobdiff_plain;f=afh.ggo;h=056a34daa893bebd203d0c7819e25f18972da5da;hp=e013cc36aa9b87749b52fc3584207f17d932961a;hb=f41688f647116d0a17513cc86c60cc9729da6502;hpb=80e46ec589d14be2fa4b0704f613a04ecb1b64c4

diff --git a/afh.ggo b/afh.ggo
index e013cc36..056a34da 100644
--- a/afh.ggo
+++ b/afh.ggo
@@ -1,12 +1,122 @@
+text "
+para_afh, the audio format handler tool, is a stand-alone program
+contained in the paraslash package for analyzing and streaming audio
+files. It can be used to
+
+	- print tech info about the given audio file to stdout.
+	In particular, the 'chunk table' of the audio file, an array
+	of offsets within the audio file, may be printed. This table
+	can be used by other programs unaware of the particular audio
+	format to stream the audio file.
+
+	- write selected parts of the given audio file in complete
+	chunks without decoding. Thus para_afh can be used to 'cut'
+	an audio file.
+
+	- write selected parts of the given audio files 'just in time'
+	to sdout.  This may be useful for third-party software that
+	is capable of reading from stdin.
+"
+
 option "loglevel" l
 #~~~~~~~~~~~~~~~~~~
 "set loglevel (0-6)"
+int typestr="level"
+default="4"
+optional
+
+defgroup "mode"
+#--------------
+groupdesc="
+	There are two modes of operation: Info mode and stream mode,
+	one of which must be selected by the corresponding option.
+	See below.
+"
+required
+
+groupoption "info" i
+#~~~~~~~~~~~~~~~~~~~
+"select info mode"
+group="mode"
+details="
+	In this mode, the program prints technical information about
+	the given audio file to stdout.
+"
 
-	int typestr="level"
-	default="4"
-	optional
+groupoption "stream" s
+#~~~~~~~~~~~~~~~~~~~~~
+"select stream mode"
+group="mode"
+details="
+	If this mode is selected, the selected parts of the content
+	of the audio file are written to stdout. Only complete chunks
+	with respect of the underlying audio format are written.
+	For example, only complete frames in case of mp3 files.
+"
+
+section "Options for info mode"
+#==============================
 
 option "chunk_table" c
+#~~~~~~~~~~~~~~~~~~~~~
 "print also the chunk table"
+flag off
+dependon="info"
+
+section "Options for stream mode"
+#================================
+
+
+option "begin_chunk" b
+#~~~~~~~~~~~~~~~~~~~~~
+"skip a number of chunks"
+int typestr="chunk_num"
+default="0"
+dependon="stream"
+optional
+details="
+	The chunk_num argument must be between -num_chunks and
+	num_chunks - 1 inclusively where num_chunks is the total number
+	of chunks which is printed when using the --info option. If
+	chunk_num is negative, the given number of chunks are counted
+	backwards from the end of the file. For example --begin_chunk
+	-100 instructs para_afh to start output at chunk num_chunks
+	- 100. This is mainly useful for cutting off the end of an
+	audio file.
+"
+
+option "end_chunk" e
+#~~~~~~~~~~~~~~~~~~~
+"only write up to chunk chunk_num"
+int typestr="chunk_num"
+dependon="stream"
+optional
+details="
+	For the chunk_num argument the same rules as for --begin_chunk
+	apply.	The default is to write up to the last chunk.
+"
+
+option "just_in_time" j
+#~~~~~~~~~~~~~~~~~~~~~~
+"use timed writes"
+flag off
+dependon="stream"
+details="
+	Write the specified chunks of data 'just in time', i.e. the
+	write of each chunk is delayed until the time it is needed
+	by the decoder/player in order to guarantee an uninterupted
+	audio stream.
+"
 
-	flag off
+option "no_header" H
+#~~~~~~~~~~~~~~~~~~~
+"do not write an audio file header"
+flag off
+dependon="stream"
+details="
+	If an audio format needs information about the audio file
+	in a format-specific header in order to be understood by
+	the decoding software, a suitable header is automatically
+	send. This option changes the default behaviour, i.e. no
+	header is written.
+"