2d860173845bd64923a4aa94e68090ada089a8b2
[mplayer.git] / TOOLS / README
1 README for the TOOLS directory
2 ==============================
3
4 Preamble
5 --------
6
7 In this directory you can find some nice scripts and code that makes
8 using MPlayer and MEncoder easier, for example scripts for DVD track
9 encoding in three pass mode or creating SVCDs from a movie.
10
11 FIXME: Document the following tools:
12
13 bmovl-test
14
15
16 MPlayer scripts in the TOOLS dir
17 --------------------------------
18
19 edgedetect.fp, emboss.fp
20
21 Author:       Reimar Döffinger
22
23 Description:  Examples of custom fragment program for OpenGL video out driver
24
25 Usage:        mplayer -vo gl:yuv=4:customprog=edgedetect.fp
26
27
28 midentify
29
30 Author:       Tobias Diedrich
31
32 Description:  Runs 'mplayer -identify' for all arguments while preventing
33               video window flashing.
34
35 Usage:        midentify file1 [file2 ...]
36
37
38 mpconsole
39
40 Author:       Rich Felker
41
42 Description:  Script to run MPlayer on the console (fbdev/mga_vid/etc.) without
43               the console text and/or flashing cursor getting in the way.
44
45 Usage:        mpconsole [mplayer options]
46
47
48 mplmult.sh
49
50 Author:       Reimar Döffinger
51
52 Description:  Example how to output video on multiple windows in sync. Might
53               be even more useful in combination with -vo ggi to distribute
54               the video arbitrarily.
55
56 Usage:        mplmult.sh <n> <options>
57               n        Number of MPlayer instances that display the video.
58               options  Any options you would pass to MPlayer, more than
59                        one file will usually not work.
60
61
62 subsearch.sh
63
64 Author:       Alex Beregszaszi
65
66 Description:  Collects subtitle files from the directory given as argument
67               ('.' if none is given) and its subdirectories and prints
68               them as a comma separated list to stdout.
69
70 Usage:        subsearch.sh [directory]
71               mplayer -sub `subsearch.sh` movie
72
73
74 wma2ogg.pl
75
76 Author:       Peter Simon
77
78 Description:  Converts WMA files to Ogg or MP3.
79
80 Usage:        wma2ogg [options] <-f FILE1 | -f FILE2 ... | -a>
81               -f, -file   filename
82               -a          converts all WMA files in the current directory
83               -t          output filetype (ogg, mp3) [default=ogg]
84               -lame       I wanna use L.A.M.E. sure enough!
85               -br         bitrate (kb/s) [default=from the WMA]
86               -del        remove WMA file(s) after the transcoding
87
88
89
90 MEncoder scripts in the TOOLS dir
91 ---------------------------------
92
93 divx2svcd
94
95 Author:       Miklos Vajna
96
97 Description:  A simple utility that creates an SVCD from a video in an AVI
98               container.
99
100 Usage:        divx2svcd <input_avi> [options]
101               see 'divx2svcd -h' for more info
102
103
104 mencvcd
105
106 Author:       Jürgen Hammelmann
107
108 Description:  Converts DVD (or anything else that MPlayer plays) to (S)VCD
109
110 Usage:        mencvcd <basename> [mencvcd options] [mplayer options]
111               see 'mencvcd -h' for more info
112
113 Note:         Requires MPlayer, mjpegtools, VCDImager, cdrdao, and optionally
114               LAME, tooLAME and SoX.
115
116
117 dvd2divxscript.pl
118
119 Author:       Florian Schilhabel
120
121 Description:  Yet another DVD to divx helper script.
122               This script encodes a DVD track in three pass mode to MPEG-4 with
123               libavcodec. Optionally it writes the resulting movie file to
124               CD-ROM the corresponding audio track to MP3. It can also shut
125               down the computer when it finishes. If you like, you can
126               watch the MEncoder output on /dev/tty8.
127
128 Usage:        --help       show help
129               --abr        (AudioBitRate) Please enter the desired bitrate this
130                            can be either [96|128|192] kbit/sec (default: 128).
131               --lang       Specify the Language of the audio track this can be
132                            for example <en> or <de> (default: <de>).
133               --dvd        Specify the DVD track you want to encode.
134               --cdsize     Specify the size of your CD-ROM (default: 700MB).
135               --shutdown   Shutdown the system, when the encoding process has
136                            finished. Needs appropriate privileges.
137               --out        Specify the name of your encoded movie. The file
138                            extension will be appended automatically.
139               --writecd    Takes the newly created movie and writes it to a
140                            CD-ROM.
141               --writedev   cdrecord device identifier, for example 0,1,0
142               --speed      writing speed (default: 4)
143               --dvd-device device to pull the video off (default: /dev/dvd)
144
145
146 aconvert
147
148 Author:       Jonas Jermann
149
150 Description:  A hack to allow MEncoder to read respectively encode from audio
151               only files.
152
153 Usage:        aconvert <"input file"> <"output file"> <"options">
154               If no options are specified the following is assumed:
155               -oac lavc -lavcopts acodec=mp3:abitrate=192
156
157 Note:         The script is probably bash dependent and it's just a quick
158               hack, feel free to improve it (or much better: fix MEncoder ;).
159
160
161
162 qepdvcd.sh
163
164 Author:       Reynaldo H. Verdejo Pinochet
165
166 Description:  converter from any supported format to VCD/SVCD PAL/NTSC
167
168 Usage:        qepdvcd.sh file <options>
169               Run with no arguments to see the list of options.
170
171 Note:         You will need vcdimager/cdrecord to master/burn the resulting
172               files.
173
174
175
176 encode2mpeglight
177
178 Author:       Giacomo Comes
179
180 Description:  Convert anything MPlayer can play to VCD/SVCD/DVD MPEG.
181
182 Usage:        encode2mpeglight -o <NAME> -n <NORM> [options] <source>
183               For help and documentation run:
184                 encode2mpeglight -h
185                 encode2mpeglight -l
186                 encode2mpeglight -doc
187
188 Note:         This script uses only MEncode/MPlayer. Check the final log
189               file for informations/warnings about the encoding process.
190
191
192 Tech scripts in the TOOLS dir
193 -----------------------------
194
195 calcbpp.pl
196
197 Author:       Moritz Bunkus
198
199 Description:  A script that calculates the $bpp for a movie, mentioned in
200               DOCS/tech/encoding-tips.txt, see that document for more info.
201
202 Usage:        calcbpp.pl <resolution> <aspect ratio> <bitrate> <fps>
203               resolution:    the cropped but unscaled resolution
204                              (use '-vf cropdetect')
205               aspect ratio:  the encoded aspect ratio. All DVDs come at
206                              720x576 but contain a flag that tells the player
207                              wether it should display the DVD at an aspect
208                              ratio of 4/3 (1.333) or at 16/9 (1.777). Have a
209                              look at MPlayer's output - there's something
210                              about 'prescaling'. That's what you are looking
211                              for.
212               bitrate:       the video bitrate in kbit/s
213               fps:           the fps
214
215               example: calcbpp.pl 720x440 16/9 896 25
216
217
218 countquant.pl
219
220 Author:       Moritz Bunkus
221
222 Description:  Counts the quantizers used for the encoding, mentioned in
223               DOCS/tech/encoding-tips.txt, see that document for more info.
224
225 Usage:        countquant.pl < divx2pass.log
226               It will print out which quantizer was used how often. If you see
227               that e.g. the lowest quantizer (vqmin=2) gets used for > 95% of
228               the frames then you can safely increase your picture size.
229
230
231 plotpsnr.pl
232
233 Author:       Jonas Jermann
234
235 Description:  Draw PSNR log graphs using gnuplot.
236
237 Usage:        plotpsnr.pl [options] <file>
238               -h, --help    Display this help message
239               -quant        Display quantizers
240               -size         Display size
241               -psnr         Display PSNR
242               -iframes      Display I-frames
243               -pframes      Display P-frames
244               -bframes      Display B-frames
245               -aframes      Display all frames in different colors
246               -cmp <file2>  Compare two files
247               -qs <style>   Quantizer style
248               -ss <style>   Size style
249               -ps <style>   PSNR style
250
251               Default: -quant -size -psnr -qs "p" -ss "i" -ps "p"
252
253 Note:         Requires gnuplot. Comparison is based on file2. Comparison
254               assumes that the frame numbers of both files fit.
255
256
257 psnr-video.sh
258
259 Author:       Matthias Wieser
260
261 Description:  Calculates the PSNR between two existing video files.
262               The PSNR is calculated frame by frame.
263               Also prints the overall PSNR.
264               The script can be used to:
265                * Compare different softwarescalers (should I use
266                  -sws 1 or -sws 2 ?)
267                * Compare different resolutions (is it better to scale
268                  down to 640x360 or to 560x320)
269                * Compare different deinterlacers
270                * Compare different video codecs
271                * Compare video filters (is it better to use -vf hqdn3d
272                  or lavcopts:nr=400)
273                * [...]
274
275 Usage:        psnr-video.sh <file1> <file2> [<frames>] [<options1>] [<options2>]
276
277               <file1> and <file2> are the video files for which the PSNR
278                 should be calculated.
279               [<frames>] is the number of frames to process, starting
280                 from frame 1.
281               [<options1>] are additional MPlayer options for <file1>
282               [<options2>] are additional MPlayer options for <file2>
283
284               A file called ./psnr.dat will be created with the following
285               content:
286
287               File;Y;Cb;Cr
288               00000001.ppm;34.23;39.54;40.06;35.426
289               00000002.ppm;33.03;38.71;39.26;34.271
290               00000003.ppm;33.45;38.91;39.28;34.655
291               00000004.ppm;32.72;38.69;38.85;33.972
292               [...]
293               00000247.ppm;35.55;40.84;42.15;36.785
294               PSNR:;35.9887
295
296 Note:         This script relies on the the tool "pnmpsnr" for the
297               frame-by-frame PSNR calculation.
298               Be aware that psnr-video.sh needs a lot of temporary space
299               in /tmp/.
300
301
302 asfinfo
303
304 Author:       Arpi
305
306 Description:  a simple ASF header display program
307
308 Usage:        asfinfo <filename.asf>
309
310 Note:         Also see MPlayer's -identify option.
311
312
313 avi-fix
314
315 Author:       Arpi
316
317 Description:  A simple tool to fix chunk sizes in RIFF AVI files.
318
319 Usage:        avi-fix [-fix] <badfile.avi>
320
321 Note:         It does not check or fix the index, to do this use
322               'mencoder -forceidx -oac copy -ovc copy'.
323
324
325 checktree.sh
326
327 Author:       Ivo van Poorten
328
329 Description:  Check the source tree for anomalies.
330
331 Usage:        checktree.sh -help
332
333 Note:         This script is meant for developers to check the current
334               source tree and/or the patches they are working on.
335
336
337 mphelp_check.py
338
339 Author:       Uoti Urpala
340
341 Description:  Check console message translations for common errors.
342
343 Usage:        mphelp_check.py [--missing] <master file> <files to check>
344
345 Note:         Compares MPlayer translation files against a master file and
346               reports conflicting arguments, extra strings not present in
347               the base file and (optionally) missing strings.
348
349
350 cpuinfo
351
352 Author:       Jürgen Keil
353
354 Description:  the prototype ../cpuinfo.c
355
356 Note:         Used by configure to emulate /proc/cpuinfo on non-Linux systems.
357
358
359 dump_mp4
360
361 Author:       Arpi
362
363 Description:  MPEG4-ES stream inspector, dumps the stream startcodes.
364
365
366 fastmemcpybench
367
368 Author:       Felix Bünemann
369
370 Description:  benchmark/testbed for fastmemcpy stuff
371
372 Note:         Also see fastmem.sh.
373
374
375 movinfo
376
377 Author:       Arpi
378
379 Description:  Show QuickTime MOV file structure.
380
381 Usage:        movinfo <filename.mov>
382
383
384 vivodump
385
386 Author:       Arpi
387
388 Description:  Dump H.263 frame headers from VIVO files.
389
390 Usage:        vivodump <input_file> <output_file>
391
392
393
394 Miscellaneous scripts in the TOOLS dir
395 --------------------------------------
396
397 subedit.pl
398
399 Author:       Michael Klepikov
400
401 Description:  A script for pipelined editing of subtitle files.
402
403 Usage:        subedit.pl [switches]
404     -if,--input-format <fmt>   input format; supported: SRT (default: SRT)
405     -of,--output-format <fmt>  output format; supported: SRT
406                                (default: input format)
407     -s,--shift <time>          shift all subtitles by <time>
408                                (format: [-]hh:mm:ss,fraction)
409     -c,--scale <time>          scale by adding <time> to overall duration
410     -f,--split-from <time>     drop subtitles that end before <time>
411     -t,--split-to <time>       drop subtitles that start after <time> (will
412                                truncate timing if it overlaps a boundary)
413     -r,--renumber              renumber SRT subtitles in output
414     -d,--debug                 enable debug output
415     -h,--help                  help message
416
417
418 w32codec_dl.pl
419
420 Author:       Tom Lees
421
422 Description:  This script will use the Windows Media Player codec download
423               infrastructure to aquire the codecs listed in codecs.conf and put
424               them in a directory named "codecs/" below the current directory.
425
426 Usage:        w32codec_dl.pl <codecs.conf location>
427
428 Note:         You will need the libwww-perl stuff and the cabextract utility
429               which can be found at http://www.kyz.uklinux.net/cabextract.php3.
430
431
432 install-w32codecs.sh
433
434 Author:       Andrea Menucci, thuglife
435
436 Description:  Downloads binary codecs from mplayerhq.hu and installs them
437               on a Debian system.
438
439 Usage:        install-w32codecs.sh install
440               install-w32codecs.sh uninstall
441
442
443 vobshift.py
444
445 Author:       Gábor Farkas
446
447 Description:  Adjust the time-info in vobsub files
448
449 Usage:        vobshift.py in.idx out.idx +8.3
450               Will shift the time by 8.3 seconds
451
452
453 subrip.c
454
455 Author:       Kim Minh Kaplan
456
457 Description:  Transform VOBsub subtitles into Subrip text subtitles using
458               GOCR/JOCR.
459
460 Usage:        subrip <vobsub basename> [subid [output filename] ]
461
462 Note:         Requires at least JOCR/GOCR 0.37.
463               You will have to change the 'vobsub_id' value if you want a
464               subtitle different from number 0. Hint: You can view the
465               subtitle that is being decoded with "display subtitle-*.pgm".
466
467
468 alaw-gen.c
469
470 Author:       Arpi
471
472 Description:  Generates alaw/ulaw tables.
473
474 Note:         Created to work around a past license issue, no longer useful.
475
476
477 avisubdump.c
478
479 Author:       Tobias Diedrich
480
481 Description:  Dumps vobsub soft subtitles streams embedded in AVI files.
482
483 Usage:        avisubdump <movie.avi>
484
485
486 vfw2menc.c
487
488 Author:       Gianluigi Tiesi
489
490 Description:  Creates a codec settings file from the Video for Windows codecs
491               found in the mplayer codec packs.
492
493 Usage:        vfw2menc -f <fourcc> -d <codec.dll> -s <settingsfile.mcf>
494               -h|--help            - displays this help
495               -d|--driver filename - dll or drv to load
496               -f|--fourcc fourcc   - fourcc of selected driver
497               -s|--save filename   - save settings to file
498               -c|--check filename  - load and show setting in filename
499               -v|--view            - displays the config dialog and do nothing
500
501 Notes:        Works on Windows/Linux x86 only.
502
503
504 modify_reg.c
505
506 Author:       Alan Nisota
507
508 Description:  Modifies registry file (usually ~/.mplayer/registry)
509
510 Usage:        modify_reg -r <registry_file> -l
511               modify_reg -r <registry_file> -k <key> [-d|-v <value>[-t <type>]]
512               -r|--registry - path to registry file
513               -l|--list     - shows all keys and values
514               -k|--key      - registry key
515               -d|--del      - delete key
516               -v|--value    - new value for key
517               -t|--type     - key type: string (default) or dword
518
519 Notes:        Necessary to use CoreAVC with MPlayer
520
521
522 realcodecs/
523
524 Author:       miscellaneous
525
526 Description:  Wrappers for Linux Real binary codecs used to analyze, alter and
527               dump the data flow between RealPlayer and its codecs.
528
529 Usage:        - Set the path to the RealPlayer codecs directory in the C files.
530               - Run 'make realcodecs'.
531               - Rename the original codecs to match the names expected in the
532                 wrapper sources. The default is to give them a "real" prefix,
533                 e.g. realcook.so.6.0.
534               - Put the wrappers in the RealPlayer codecs directory.
535
536 Notes:        Known to work at least on Linux x86 with RealPlayer8.
537
538
539
540 netstream - access remote streams
541 ---------------------------------
542
543 NOTE: netstream does not link at the moment - help welcome.
544
545 netstream allows you to access most MPlayer stream types from a remote host.
546 The main purpose of this feature is to make it possible to directly use the
547 CD or DVD drive of another computer on the network (provided you have the
548 required bandwidth). On the downside some stream types (currently TV and MF)
549 are not usable remotely because they are implemented at the demuxer level.
550
551 Be aware that currently the server is not secure at all.
552
553 Compile the server by running 'make netstream' and then copy the netstream
554 binary to the right place on your system (usually /usr/local/bin on Unix).
555 Start the netstream server on the computer you intend to access remotely.
556 There are no command line arguments.
557
558 Play the second track of a VCD on the server with:
559
560   mplayer -cache 5000 mpst://servername/vcd://2
561
562 Access files on this server with:
563
564   mplayer -cache 5000 mpst://servername//usr/local/movies/lol.avi
565
566 Note that paths which do not start with a / will be interpreted as relative to
567 the directory where the server is running. The '-cache' option is not needed
568 but highly recommended.