para_afh: Accept negative values for begin_chunk and end_chunk.
[paraslash.git] / afh.ggo
1 text "
2 para_afh, the audio format handler tool, is a stand-alone program
3 contained in the paraslash package for analyzing and streaming audio
4 files. It can be used to
5
6 - print tech info about the given audio file to stdout.
7 In particular, the 'chunk table' of the audio file, an array
8 of offsets within the audio file, may be printed. This table
9 can be used by other programs unaware of the particular audio
10 format to stream the audio file.
11
12 - write selected parts of the given audio file in complete
13 chunks without decoding. Thus para_afh can be used to 'cut'
14 an audio file.
15
16 - write selected parts of the given audio files 'just in time'
17 to sdout. This may be useful for third-party software that
18 is capable of reading from stdin.
19 "
20
21 option "loglevel" l
22 #~~~~~~~~~~~~~~~~~~
23 "set loglevel (0-6)"
24 int typestr="level"
25 default="4"
26 optional
27
28 defgroup "mode"
29 #--------------
30 groupdesc="
31 There are two modes of operation: Info mode and stream mode,
32 one of which must be selected by the corresponding option.
33 See below.
34 "
35 required
36
37 groupoption "info" i
38 #~~~~~~~~~~~~~~~~~~~
39 "select info mode"
40 group="mode"
41 details="
42 In this mode, the program prints technical information about
43 the given audio file to stdout.
44 "
45
46 groupoption "stream" s
47 #~~~~~~~~~~~~~~~~~~~~~
48 "select stream mode"
49 group="mode"
50 details="
51 If this mode is selected, the selected parts of the content
52 of the audio file are written to stdout. Only complete chunks
53 with respect of the underlying audio format are written.
54 For example, only complete frames in case of mp3 files.
55 "
56
57 section "Options for info mode"
58 #==============================
59
60 option "chunk_table" c
61 #~~~~~~~~~~~~~~~~~~~~~
62 "print also the chunk table"
63 flag off
64 dependon="info"
65
66 section "Options for stream mode"
67 #================================
68
69
70 option "begin_chunk" b
71 #~~~~~~~~~~~~~~~~~~~~~
72 "skip a number of chunks"
73 int typestr="chunk_num"
74 default="0"
75 dependon="stream"
76 optional
77 details="
78 The chunk_num argument must be between -num_chunks and
79 num_chunks - 1 inclusively where num_chunks is the total number
80 of chunks which is printed when using the --info option. If
81 chunk_num is negative, the given number of chunks are counted
82 backwards from the end of the file. For example --begin_chunk
83 -100 instructs para_afh to start output at chunk num_chunks
84 - 100. This is mainly useful for cutting off the end of an
85 audio file.
86 "
87
88 option "end_chunk" e
89 #~~~~~~~~~~~~~~~~~~~
90 "only write up to chunk chunk_num"
91 int typestr="chunk_num"
92 dependon="stream"
93 optional
94 details="
95 For the chunk_num argument the same rules as for --begin_chunk
96 apply. The default is to write up to the last chunk.
97 "
98
99 option "just_in_time" j
100 #~~~~~~~~~~~~~~~~~~~~~~
101 "use timed writes"
102 flag off
103 dependon="stream"
104 details="
105 Write the specified chunks of data 'just in time', i.e. the
106 write of each chunk is delayed until the time it is needed
107 by the decoder/player in order to guarantee an uninterupted
108 audio stream.
109 "
110
111 option "no_header" H
112 #~~~~~~~~~~~~~~~~~~~
113 "do not write an audio file header"
114 flag off
115 dependon="stream"
116 details="
117 If an audio format needs information about the audio file
118 in a format-specific header in order to be understood by
119 the decoding software, a suitable header is automatically
120 send. This option changes the default behaviour so that no
121 header is sent.
122 "