From f6fb536f87e687a4aacca75dd9ad1c7b71ffa731 Mon Sep 17 00:00:00 2001 From: Uoti Urpala Date: Sat, 29 Jan 2011 03:27:47 +0200 Subject: DOCS/tech/: remove several obsolete files Some of the files contain some usable stuff, but overall they're obsolete enough that it's better to remove the current versions. --- DOCS/tech/TODO | 93 ----- DOCS/tech/binary-packaging.txt | 207 ---------- DOCS/tech/code-documentation.txt | 132 ------ DOCS/tech/codec-devel.txt | 207 ---------- DOCS/tech/dvdnav-howto.txt | 42 -- DOCS/tech/encoding-guide.txt | 138 ------- DOCS/tech/encoding-tips.txt | 725 --------------------------------- DOCS/tech/mingw-crosscompile.txt | 32 -- DOCS/tech/mirrors/mirror_howto.txt | 230 ----------- DOCS/tech/mirrors/update_mplayer_rsync | 37 -- DOCS/tech/mpdsf.txt | 28 -- DOCS/tech/osd.txt | 86 ---- DOCS/tech/patches.txt | 119 ------ DOCS/tech/release-howto.txt | 60 --- DOCS/tech/snow.txt | 89 ---- DOCS/tech/translations.txt | 138 ------- DOCS/tech/wishlist | 181 -------- 17 files changed, 2544 deletions(-) delete mode 100644 DOCS/tech/TODO delete mode 100644 DOCS/tech/binary-packaging.txt delete mode 100644 DOCS/tech/code-documentation.txt delete mode 100644 DOCS/tech/codec-devel.txt delete mode 100644 DOCS/tech/dvdnav-howto.txt delete mode 100644 DOCS/tech/encoding-guide.txt delete mode 100644 DOCS/tech/encoding-tips.txt delete mode 100644 DOCS/tech/mingw-crosscompile.txt delete mode 100644 DOCS/tech/mirrors/mirror_howto.txt delete mode 100644 DOCS/tech/mirrors/update_mplayer_rsync delete mode 100644 DOCS/tech/mpdsf.txt delete mode 100644 DOCS/tech/osd.txt delete mode 100644 DOCS/tech/patches.txt delete mode 100644 DOCS/tech/release-howto.txt delete mode 100644 DOCS/tech/snow.txt delete mode 100644 DOCS/tech/translations.txt delete mode 100644 DOCS/tech/wishlist (limited to 'DOCS') diff --git a/DOCS/tech/TODO b/DOCS/tech/TODO deleted file mode 100644 index cc3c3e2ef4..0000000000 --- a/DOCS/tech/TODO +++ /dev/null @@ -1,93 +0,0 @@ -TODO: -===== - -SVN CLEANUP work: -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- remove -vf yuy2, yvu9 -- change build & install stuff (cross-lib dependency etc) - - re-design makefile dependency system -- start using the ffmpeg patch tracker (roundup) -- check if these still matter & fix & apply the needed patches: - - MPlayer-0.90rc2.rawyuv.diff - raw YUV (I420) video 'encoder' - (checks requires for stride==width, and aligned planes) - - bte.diff - something input plugin (uses fork() ) - - lavc_statsfile_errorchecking-patch - handle errors writing to logfile - - fastermemcpy.diff - cacheline-size dependent optimizations - - fire-x86-runtime-options.diff - en/disable (force) cpu features runtime - (needs to be integrated with --runtime-cpu-detection en/disabled modes) - - mga_vid_laced.diff - buggy interlace support into mga_vid - - patch_sortsub_disable-1.3x.diff - remove --disable-sortsub - - mplayer-0.90rc3-fixfbdev.patch - ugly hack to fix multiple file & -vo fbdev - - fix and apply dvd menu patches. -- review and implement draw_slice() support in video filters -- remove vidix/ and use external vidix - -FOR THE NEXT RELEASE: -~~~~~~~~~~~~~~~~~~~~~~ -- fix vo_svga vs. -vf scale - DONE? -- Re: [MPlayer-cvslog] CVS: main/libvo vo_vesa.c,1.82,1.83 - This patch makes mplayer unusable in console mode, always leaves the - console in graphic mode. -- Dec 19: [BUG] mencoder+mp3lame creates desynced AVI (<=22Khz support missing) -- finish testing /old-incoming/ samples -- fix partial -dr + ffmpeg + B frames (different stride per frame) -- implementing 8bpp support in vo_x11.c -- cleanup qtaudio/qtvideo (move globals to context) -- cleanup DMO interfaces -- Port GUI code to plain gtk without using X functions (any volunteers??? we really need help here) - -FOR THE v1.00 RELEASE: -~~~~~~~~~~~~~~~~~~~~~~ - -cruft removal: -- remove support for skins directories using the obsolete name 'Skin' - -DVB: -- display OSD and subtitles using DVB card's OSD - -avi demuxer: (needs rewrite) -- implement hardcore bruteforce avi re-sync for broken files (-forceidx) -- fix for growing avi files (movi_end pos > stream->end_pos) -- implement forward seeking in avi streams with no index - -mencoder: -- add ogg/vorbis audio encoder -- stop/resume - -DOCS: -- merge iive's XvMC docs into video.xml -- enhance and merge the FAQ with the wiki FAQ -- split man page into mplayer.1 and mencoder.1 - - -FUTURE: -~~~~~~~ - -demuxer: -- demux_mpg: support for VDR's index files for more accurate seeking - - finish evo support -- implement seeking for YUV4MPEG_2_ - -decoders: -- fix DLL loading problems - - vfw: pegasusm, pegasusl, pegasusmwv, 3ivX, alaris, vcr1, pim1, rricm, mvi1, mvi2 - - dshow: morgands - - qtvideo and qtaudio: all crashing codecs - - update qt binary codec to latest version - -other: -- dvd server -- mga_vid crtc2 fix -- X11 Render support into DGA for OSD (from the DOCS;) - -DOCS: -- finish encoding for embedded devices howto - -stream: -- native or nemesi rtsp support - -remove externals: -- remove tremor when ffvorbis has integer-only decoder. -- remove libmpeg2 when ffmpeg12 is faster -- remove mp3lib when ffmp3 is faster -- remove libfaad2 after soc aac is 100% diff --git a/DOCS/tech/binary-packaging.txt b/DOCS/tech/binary-packaging.txt deleted file mode 100644 index 6cc485ef2b..0000000000 --- a/DOCS/tech/binary-packaging.txt +++ /dev/null @@ -1,207 +0,0 @@ - ________________________________________________ - How to make good binary package(s) of MPlayer? - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - by Dominik 'Rathann' Mierzejewski - -About this document -~~~~~~~~~~~~~~~~~~~ - -With the release of MPlayer 0.90pre9, all licensing issues have been -eliminated and all code is licensed under the GPL, which allows -independent packagers to create and distribute binary packages. At first, -this was discouraged by some of the developers, but the users' demand for -ready-to-use binary packages convinced some people to create them. -Unfortunately, many currently available packages are crippled, include -their own obsolete config files or are mispackaged in some other way. This -document aims to establish a common set of packaging guidelines so that -proper official binary packages for various Linux distributions and other -operating systems can be maintained. - - -Conventions -~~~~~~~~~~~ -Whenever you see "MUST", it means that following the mentioned guideline -is required. Whenever you see "SHOULD", it means that following the -guideline is highly recommended, but not required. - - -Minimum feature set -~~~~~~~~~~~~~~~~~~~ -Due to MPlayer design, it is impossible to simply include all possible -features and enable or disable them at runtime. That is why packagers -SHOULD avoid "dependency hell" by retaining a reasonable, limited default -feature set. After some discussion with other developers, we agreed that -the following features MUST be included in any official binary package: - -* audio/video output - - fbdev - - JPEG/PNG/TGA - - (X)MGA - - OSS - - tdfxfb - - (c/x)vidix - - X11/Xvideo - -* codecs - - FAAD(internal) - - libavcodec(internal) - - native codecs (libmpeg2/mp3lib) - - Vorbis Tremor codec(internal) - - RealPlayer codecs support (*) - - Win32/VfW/DShow/QT codecs support (*) - - XAnim codecs support (*) - -* general: - - FreeType fonts support - - HTML documentation - - large file support - - man page(s) - -* input/demuxers: - - DVD(libdvdread4/libdvdnav) - - streaming - - Matroska(internal) - - (S)VCD - - tv(v4l/v4l2) - -(*) if available for your OS/hardware - -Including other features, like LIVE.COM streaming or JACK support, is -acceptable. They SHOULD, however, be build-time configurable, with the -default build configuration containing the above set. - -It seems there are some packages in the wild which lack included docs. -This is VERY BAD, as it forces users to look for outside support when most -of the common problems are easy to solve and are already described in the -docs, thus increasing the number of repeated posts in MPlayer mailing -lists. Binary packages MUST include both the man page and HTML -documentation. Translated versions SHOULD be included, even if your -package management system does not provide specific support for -internationalization. - -Libavcodec MUST always be in the latest development version and it SHOULD -be linked statically into the mplayer binary, because MPlayer requires a -recent libavcodec snapshot. It is acceptable to use a shared (again, recent) -version of libavcodec, but you must be aware that this disables some of -MPlayer's functions (for example, some postprocessing filters) and sacrifices -speed. - -Support for binary codecs SHOULD be present to the extent that the combination -of operating system and CPU architecture permits, but it MUST NOT result in a -hard dependency on a binary codecs package. MPlayer is fully functional without -external binary codecs. If you package binary codecs yourself, package the -essential codecs package, not the all codecs package. - -Bitmap fonts are deprecated, don't package them. Use scalable (Type1/TrueType) -fonts instead. - - -File locations -~~~~~~~~~~~~~~ -In general, you SHOULD follow your distribution guidelines. For example, -for Red Hat and Fedora RPMs I am using FHS-compliant paths: - -/etc/mplayer/ system-wide configs -/usr/bin/ binaries -/usr/lib/codecs/ binary codecs -/usr/lib64/codecs/ binary codecs on 64bit Linux -/usr/share/doc/mplayer-version/ docs -/usr/share/man/man1/ man page -/usr/share/man/XX/man1/ translated man page - -You MUST NOT include the codecs.conf file in your package. It is useful -only for development purposes and often causes obscure problems for users. - -Please avoid using the deprecated paths for binary codecs (/usr/lib/win32/) -and skins (/usr/share/mplayer/Skin/). - - -One package or many packages? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Although it is tempting to simply provide a single all-in-one package, -I think it is best to split MPlayer into several packages. It may be -a little more troublesome for less clueful users, but it allows you to -install only what you need. This is the layout I am using for Red Hat and -Fedora RPMs: - -mencoder contains MEncoder binary (mencoder) -mplayer contains MPlayer binary config files, man pages and - documentation; -mplayer-codecs-* contain binary codecs available from MPlayer's site - -There is no strict policy for now, just use your common sense. - - -Compilation -~~~~~~~~~~~ -While it is acceptable to provide packages optimized for specific CPUs, -you MUST provide at least one "lowest common denominator" package set -that will work on all CPUs. This means it MUST be configured with the ---enable-runtime-cpudetection option. Building for specific CPUs requires -disabling this option, but try to make sure that users cannot accidentally -install a package not suitable for their CPU. With RPMs, for example, this -is handled automatically, when building with the "--target arch" rpm option. - -Compiler flags MUST be set to either configure-generated CFLAGS or something -as close to them as possible. - -Users MUST be able to rebuild your source package without hand-editing on -any system with the same distribution installed. Remember to disable -(--disable-xxx) any optional features, because MPlayer's configure script -autodetects most of them. This ensures that binary package builds are -deterministic -- that is, provided they have at least the required -development packages installed, two different people using the same -distribution will get binaries with the same dependencies. - -You SHOULD provide an option to rebuild the package with full debug -information enabled (by passing --enable-debug=3 to ./configure and -disabling any stripping of binaries and libs during the build process). -For example my source RPM can be rebuilt with a "--with debug" option, which -does just that, making it easier to supply gdb information along with any -bug reports, while retaining all benefits of using binary packages. - - -Modifications -~~~~~~~~~~~~~ - -You MUST modify `mplayer -v` output so that it is clear that a user is -using your binary package, by patching version.h and modifying the version -string inside. Suggested convention is to include distribution name and, -possibly, the signature of the packager or the repository. For example: - -original: - MPlayer 1.0pre5-3.3.2 (C) 2000-2004 MPlayer Team -modified: - MPlayer 1.0pre5-Fedora-GS-3.3.2 (C) 2000-2004 MPlayer Team - MPlayer 1.0pre5-Mandrake-PLF-3.2.3 (C) 2000-2004 MPlayer Team - MPlayer 1.0pre5-Solaris-3.4.0 (C) 2000-2004 MPlayer Team - -If you patch MPlayer, send your patches to us! We will try to integrate them. -Furthermore, we're often able to come up with a cleaner or more general -solution to your problem. - -If you have modified configuration files or similar, please patch the official -one instead of copying it into your package. This way you will automatically -pick up changes we make to it. - -Do not override video and audio output selection in the system-wide config -file. MPlayer will try to pick the best VO and AO itself and fall back -gracefully. If you want to give priority to some AO, add a comma at the end -of the line so that MPlayer can still fall back on others, for example: -ao=alsa, - -Tips and tricks -~~~~~~~~~~~~~~~ -To provide man pages for all MPlayer suite binaries (mplayer, mencoder), you -can use man-links instead of regular symbolic links. -Creating a mencoder man page linked to mplayer is as simple as: - - echo ".so mplayer.1" >> mencoder.1 - -A similar trick can be used for "man gmplayer". This avoids problems with -gzipped man pages and symbolic links. - -Newer Red Hat and Fedora distributions keep localized man pages encoded in -UTF-8. If your distribution does the same, make sure you convert MPlayer's -translated man pages to UTF-8 so that man mplayer works for locales other -than English. diff --git a/DOCS/tech/code-documentation.txt b/DOCS/tech/code-documentation.txt deleted file mode 100644 index 9213a79715..0000000000 --- a/DOCS/tech/code-documentation.txt +++ /dev/null @@ -1,132 +0,0 @@ -Code documentation guidelines -============================= - -About this guide ----------------- - -Due to the ever increasing complexity and size of MPlayer it became quite hard -to maintain the code and add new features. Part of this problem is the lack -of proper documentation what the code in question does and how it is doing it. -To tackle this problem every part of MPlayer should follow these guidelines -on what and how code should be documented. - - -Doxygen -------- - -MPlayer uses doxygen for its code documentation. It generates HTML files -which contain specially tagged comment lines from the code including -cross references. To generate it type `make doxygen` in the source root -directory. It will generate the files in DOCS/tech/doxygen. To clear them -again, you can use `make doxygen_clean`. -For further information about doxygen and its sources please have a look -at their website: http://doxygen.sf.net - - -What should be documented? --------------------------- - -- every function, no matter whether it is globally or just locally used - * what the function does - * all parameters and return values of the function and their valid ranges - * all side effects (to passed parameters, globals etc) - * all assumptions made within the function - -- global, file local and important variables - * what it is used for - * its valid range - * where it is set (optional) - * where validity checking is done (optional, mandatory for variables which - are set by something external, e.g. user parameters, file information etc) - -- #define, typedefs, structs - * all global definitions - * all local definitions whose use is not immediately clear by their name - (as a rule of thumb, it's better to document too much than not enough) - * all dependencies - -- non-trivial parts of the code - * tricky parts - * important parts - * special side effects - * assumptions of the code - * string operations and why they are safe - -- workarounds - * why they are needed - * how they work - * what side effects they have - -If you are unsure whether a comment is needed or not, add one. - - -How should it be documented? ----------------------------- - -All comments should be in correct and clear English. Any other language is -not allowed. The language used should be kept simple as the code will be -read mostly by non-native speakers. For function and variable documentation, -a style usable by doxygen should be used. See section 3 "Documenting the code" -of the doxygen manual for an introduction. A very short overview follows: - -Doxygen includes only special comments in the documentation, those are: - -/// This is a line used by doxygen. - -/** this one, too */ - -/** these -here -of -course, -too */ - -//! this form can be also used - -// This line isn't included in doxygen documentation. - -/* Neither is this. */ - -Doxygen comments should come before the definition: - -/** description */ -int a_variable; - -However, you can use '<' to describe things AFTER they are defined, like this: - -int some_var; ///< description -#define foo(x) (x + 2) /**< returns x plus 2 */ - -There are a couple of special tags for doxygen: - -\brief - Gives a brief description of a function. -\param - Describes a specific . -\return - Describes the return value. -\a - Mark next word as a reference to a parameter. -\e - Use italic font for the next word. -\b - Use bold font for the next word. -\c - Use typewriter font for the next word. -\sa - Adds a section with crossreferences. -\bug - Describe a known bug. -\todo - Add a todo list. -\attention - Add a section for something that needs attention. -\warning - Add a section for a warning. -\anchor - Set an invisible anchor which can be used to create a link with \ref. -\ref [] - Add a link to . - -For a complete list of tags please read section 20 "Special commands" of the -doxygen manual. diff --git a/DOCS/tech/codec-devel.txt b/DOCS/tech/codec-devel.txt deleted file mode 100644 index bc968c9499..0000000000 --- a/DOCS/tech/codec-devel.txt +++ /dev/null @@ -1,207 +0,0 @@ -A Guide To Developing MPlayer Codecs -by Mike Melanson (melanson at pcisys dot net) -updated to libmpcodecs arch by A'rpi - -SEE ALSO: libmpcodecs.txt !!! - -NOTE: If you want to implement a new native codec, please add it to -libavcodec. libmpcodecs is considered mostly deprecated, except for wrappers -around external libraries and codecs requiring binary support. - -Introduction ------------- -I've developed a number of open source decoders for the MPlayer project, -for both audio and video data. As such, I feel I'm qualified to document a -few notes about developing new codecs for the codebase. - -As always, the best way to learn how to incorporate a new codec is to -study a bunch of existing code. This document is supplementary material to -the code, meant to give some tips, pointers, and a general roadmap. - -A note about terminology: "Codec" stands for coder/decoder (or -compressor/decompressor, if you prefer). The term refers to a module that -can both encode and decode data. However, this document focuses primarily -on incorporating decoders. Still, the terms "decoder" and "codec" are -often used interchangeably. - -Necessary Materials -------------------- -So you've decided that you want to implement a new decoder for -MPlayer. There are a few things you will need: - -- Knowledge of the codec to be implemented: You will need to know the data -format of the chunks that MPlayer will pass to you. You will need to know -how to take apart the data structures inside. You will need to know the -algorithmic operations that need to be performed on the data in order to -reconstruct the original media. - -- Sample media: Preferably, lots of it. You will need media encoded in -your data format and stored in a media file format that MPlayer knows how -to parse (these include AVI, ASF, MOV, RM, VIVO, among others). If the -encoded data is stored in a media file format that MPlayer doesn't -understand, then you will either need to somehow convert the format to a -media file format that the program does understand, or write your own -MPlayer file demuxer that can handle the data. Writing a file demuxer -is beyond the scope of this document. - Try to obtain media that stresses all possible modes of a -decoder. If an audio codec is known to work with both mono and stereo -data, search for sample media of both types. If a video codec is known to -work at 7 different bit depths, then, as painful as it may be, do what you -can to obtain sample media encoded for each of the 7 bit depths. - -- Latest Subversion snapshot: It's always useful to develop code for the very -latest development version of MPlayer. Be sure to update your local Subversion -copy often. - -- General programming knowledge, working Linux development environment: I -would hope that these items would go without saying, but you never know. - -Typical Development Cycle -------------------------- -1) Set up basic infrastructure -First things first, there's a big song and dance to go through in order to -let the MPlayer program know that you have a new codec to incorporate. - -First, modify your local copy of codecs.conf. It may be system-shared or -in your home directory. Add a new entry for your codec. If it's an open -source codec, it would be a good idea to place the new entry with the rest -of the open source codecs. When you're confident that you have the entry -right, be sure to add it to etc/codecs.conf in your workspace. See the -file codecs.conf.txt for a detailed description of the format of this -file. Create a new audiocodec or videocodec block with the proper info, -FOURCCs/format numbers, output formats, and a unique driver name. Remember -the driver name. - -Next, create a new source file which contains the main decoding function -that MPlayer will call to decode data. Eventually, you may have multiple -files which comprise your decoder, but let's start simple here. -For audio codecs, see ad_sample.c skeleton. For video, choose one of the -existing vd_*.c files which you think is close to your codec in behaviour. - -Next, modify the Makefile so that it will compile your new source file. -Also, add your codec to the array in ad.c (for audio) or vd.c (for video). - -Next, compile the project and see if you have everything correct so far. - -Next, you want to make sure that the encoded data is making it to your -decoding function in the first place. This may sound like a trivial -exercise, but there are a lot of things that can go wrong (and I've -watched most of them go wrong in my experience). At the beginning of your -skeleton decoder function, enter the following code: - int i; - for (i = 0; i < 16; i++) - printf ("%02X ", input[i]); - printf ("\n"); -When you compile and run MPlayer, your decoder function will print the -first 16 bytes of each data chunk that it receives. Open the sample media -in a hex editor and reconcile what you see on the screen with what -you find in the file. If the decoder is printing the first 16 bytes of -each block, that's a good sign that you're ready to move on to step -2. Otherwise, you need to figure out why the data isn't getting to your -decoder. Is your decoder even being invoked? If not, why not? - -2) Develop the decoder -Go for it. Remember to make it work, first, then make it work fast. Some -specific tips: - -What output formats should you support in your decoder? Whatever makes -sense. YUV output is always preferable over RGB output. Generally, if a -codec uses a YUV data as its source data, you will be able to decode a -frame of YUV data. If a codec takes RGB data as its input, as many older -video codecs do, then there's no point in supporting YUV output; just -output as many RGB formats as possible. - -The most preferred output format for video data is YV12. This is because -MPlayer supports a multitude of hardware devices that can display, scale, -and filter this type of data directly. MPlayer also has a bunch of -optimized conversion functions that can convert YV12 data to any other -type of output data. - -If you do take the RGB output route, you should be aware that MPlayer -actually orders packed RGB data as BGR. If you're decoding into a BGR24 -buffer, the output will look like: - B G R B G R B G R B ... -If you're decoding into a BGR32 buffer, there will need to be an -additional (unused) byte after each BGR triplet: - B G R - B G R - B G ... - -Make liberal use of sanity checks. Start by including the file mp_msg.h at -the start of your decoder. Then you can use the mp_msg() function as you -would a normal printf() statement. Whenever your decoder notices a strange -bit of data or an odd condition, print a message such as: - mp_msg(MSGT_DECVIDEO, MSGL_WARN, "Odd data encountered: %d\n", data); -Obviously, you should make the message a little more -descriptive, for your benefit. MSGL_WARN is a good message level for this -type of information. Look in mp_msg.h for all of the error levels. You can -even make MPlayer bail out completely by using MSGL_FATAL, but that should -never be necessary at the data decoder level. - -What conditions should trigger a warning? Anything, and I mean *anything* -out of the ordinary. Many chunks of compressed video data contain headers -with data such as width, height, and chunk size. Reconcile these fields -with the parameters passed into the decoding function (if you set it up to -take those parameters). Such data should match up. If it doesn't, issue a -warning and make an executive decision in the code about which data to -believe (personally, I always lend more weight to the data that was passed -into the decoder function, than the data that comes from the container file's -header). If there's supposed to be a magic number embedded in, or computed -from, the chunk's header, issue a warning if it isn't correct. - -Whenever you're about the index into a memory array with an index that -could theoretically be out of range, then test that the index is in range, -no matter how tedious it seems. Accessing outside of your memory range is, -after all, the number 1 cause of segmentation faults. Never trust that all -the data passed to you will be correct. If an array index suddenly winds -up out of range, it's probably best to issue a warning about it and bail -out of the decoder (but not the whole application). - -Writing all of these warning statements may seem insipid, but consider -that if you don't do it when you start writing your decoder, you'll -probably end up doing it later on when your decoder isn't working properly -and you need to figure out why (believe me, I know). - -3) Debug and test the decoder -If you're extremely lucky, the decoder will work the first time. If you're -very lucky, it will work after you've reviewed your code a few times and -corrected a few obvious programming mistakes. Realistically, you will -write the decoder, review it many times and fix many obvious and subtle -programming errors, and still have to go through an elaborate debug -process in order to get the decoder to a minimally functional state. - -Big hint: Ask for all warnings. You know, the -Wall option in -gcc? It's very useful to develop your codec while running in debug -mode. In order to compile MPlayer with debug support (which includes -Wall -for all gcc operations), use the --enable-debug option when configuring -the project. Pay attention to all warnings and make it a goal to get -rid of every single one. I'll never forget when the compiler warned me -that there was no point in clamping a signed 16-bit variable within a -signed 16-bit range (the calculation to be clamped was supposed to be -stored in a signed 32-bit variable and then stored in the signed 16-bit -variable). I sat stunned for a moment, feeling like I had just dodged a -bullet as I knew that would have taken me hours to debug that kind of -mistake. - -4) Contribute decoder to codebase -Create a patch with the "diff -u" format and email it to the MPlayer -development team for approval. You will likely need to diff the following -files: -- Makefile -- etc/codecs.conf -- ad.c or vd.c -Of course, you will need to include your newly-created file(s): -vd_.c -OR- ad_.c. If you contribute enough decoders, the -development team may even grant you write privileges to the Subversion -repository. - -5) Wait for bug reports to start rolling in -You may think you're finished when you release the codec and if you're -extremely lucky, you will be right. However, it's more likely that people -will start throwing all kinds of oddball media at your decoder that it -never counted on. Cheer up; take comfort in knowing that people are -testing your code and attempting to use it as a real world -application. Download the problem media that people upload to the MPlayer -FTP site and get back to work, implementing fixed code that addresses the -issues. Contribute more patches and encourage people to hammer on your -decoder even more. This is how you make your decoder rock-solid. - -EOF diff --git a/DOCS/tech/dvdnav-howto.txt b/DOCS/tech/dvdnav-howto.txt deleted file mode 100644 index 4bba42d975..0000000000 --- a/DOCS/tech/dvdnav-howto.txt +++ /dev/null @@ -1,42 +0,0 @@ -How to compile MPlayer with support for dvdnav: - -Since the versions of dvdnav and dvdread generally shipped with most Linux -distributions are outdated and unmaintained remove any traces of dvdnav and -dvdread from your computer (something like the command below should suffice): -$ rm -rf /usr/lib/libdvdnav* /usr/lib/libdvdread* /usr/include/dvdnav* \ - /usr/include/dvdread* /usr/local/lib/libdvdnav* \ - /usr/local/lib/libdvdread* /usr/local/include/dvdnav* \ - /usr/local/include/dvdread* /usr/bin/dvdnav-config \ - /usr/local/bin/dvdnav-config - -Now download dvdnav from MPHQ libdvdread and libdvdnav (in this order) : -$ svn co svn://svn.mplayerhq.hu/dvdnav/trunk/libdvdread libdvdread -$ cd libdvdread -$ ./autogen.sh && ./configure && make -(or, if you feel brave and want to help us improve the new build system) -$ ./configure2 && make -install it as root with -$ make install - -$ svn co svn://svn.mplayerhq.hu/dvdnav/trunk/libdvdnav libdvdnav -$ cd libdvdnav -$ ./autogen.sh && ./configure && make -(or, if you feel brave and want to help us improve the new build system) -$ ./configure2 && make -install it as root with -$ make install - -From within the MPlayer source tree run -$ ./configure --disable-dvdread-internal -followed by your preferred parameters. -Be warned that you *MUST* disable MPlayer's internal copy of dvdread or something -- most likely - won't work as expected (if at all). -After configure is run it should say that support for dvdnav and dvdread was -enabled. If not, investigate the dvdnav and dvdread sections in config.log -and try to understand what went wrong. If you can't solve the problem yourself -post the two sections to mplayer-users. - -Notice: Audio and subtitle language selection by means of menus doesn't work yet. -Nonetheless they can be switched as usual at any time during -playback by pressing '#' and 'j' (or the keys you chose to override those two -bindings). diff --git a/DOCS/tech/encoding-guide.txt b/DOCS/tech/encoding-guide.txt deleted file mode 100644 index 0393bcbb5f..0000000000 --- a/DOCS/tech/encoding-guide.txt +++ /dev/null @@ -1,138 +0,0 @@ -Topics: - - -I. Preparing to encode - 1. Identifying source material and framerate - 2. Selecting the quality you want - 3. Constraints for efficient encoding - 4. Cropping and scaling - 5. Choosing resolution and bitrate - -II. Containers and codecs - 1. Where the movie will be played - 2. Constraints of DVD, SVCD, and VCD - 3. Limitations of AVI container - -III. Basic MEncoder usage - 1. Selecting codecs & format - 2. Selecting input file or device - 3. Loading video filters - 4. Notes on A/V sync - -IV. Encoding procedures - 1. Encoding progressive video - 2. Two-pass encoding - 3. Encoding interlaced video - 4. Deinterlacing - 5. Inverse telecine - 6. Capturing TV input - 7. Dealing with mixed-source content - 8. Low-quality & damaged sources - -V. Optimizing encoding quality - 1. Noise removal - 2. Pure quality-gain options - 3. Questionable-gain options - 4. Advanced MPEG-4 features - - - - -II. Containers and codecs - -II.1. Where the movie will be played - -Perhaps the most important factor to choosing the format in which you -will encode your movie is where you want to be able to play it. -Usually this involves a tradeoff between quality and features, since -the formats supported by the widest variety of players are also the -worst in regards to compression. - -If you want to be able to play your encode on standalone/set-top -players, your primary choices are DVD, VCD, and SVCD. There are also -extensions such as KVCD and XVCD which violate the standards but work -on many players and deliver higher quality. Modern players are -beginning to support MPEG-4 ("DivX") movies in AVI and perhaps other -containers as well, but these are often buggy and require you to -restrict your encodes to certain subsets of the full MPEG-4 -functionality. - -If you wish to be able to share your movies with Windows or Macintosh -users, without them having to install additional software, your -choices are very limited. The ancient MPEG-1 format with MP2 or PCM -audio is probably the only choice that is universally supported. -Interoperability with Windows/Mac also comes into play when deciding -how to encode and whether to scale to preserve aspect, since popular -media player applications for these systems do not honor the aspect -ratio encoding stored in MPEG-4 avi files. - - - -IV.2. Two-pass encoding - -The complexity (and thus the number of bits) required to compress the -frames of a movie can vary greatly from one scene to another. Modern -video encoders can adjust to these needs as they go and vary the -bitrate. However, they cannot exceed the requested average bitrate for -long stretches of time, because they do not know the bitrate needs of -future scenes. - -Two-pass encoding solves this problem by encoding the movie twice. -During the first pass, statistics are generated regarding the number -of bits used by each frame and the quantization level (quality) at -which it was encoded. Then, when the second pass begins, the encoder -reads these statistics and redistributes the bits from frames where -they are in excess to frames that are suffering from low quality. - -In order for the process to work properly, the encoder should be given -exactly the same sequence of frames during both passes. This means -that the same filters must be used, the same encoder parameters must -be used (with the possible exception of bitrate), and the same frame -drops and duplications (if any) must take place. - -In theory it's possible to use -oac pcm or -oac copy during the first -pass to avoid spending time encoding the audio. However, this can -result in slight variations in which frames get dropped or duplicated, -so it may be preferable to encode the audio during the first pass as -well as the second. This also allows you to examine the final audio -bitrate and filesize, and to adjust the audio or video bitrate -slightly between passes if you don't meet your target size. - -Here is an example: - - Encoding from an existing AVI file - 500 kbit/sec MPEG-4 video - 96 kbit/sec average-bitrate MP3 audio - - mencoder bar.avi -vf scale=448:336 -mc 0 -oac mp3lame -lameopts \ - abr:br=96 -ovc lavc -lavcopts vcodec=mpeg4:vbitrate=500:vpass=1 - - mencoder bar.avi -vf scale=448:336 -mc 0 -oac mp3lame -lameopts \ - abr:br=96 -ovc lavc -lavcopts vcodec=mpeg4:vbitrate=500:vpass=2 - -If you do not want to overwrite the output from the first pass when -you begin the second, you can use the -o option to choose a different -output filename. Note the addition of the vpass option in this -example. If vpass is not specified, single-pass encoding is performed. -If vpass=1, a log file is written with statistics from the first pass. -If vpass=2, the log file is read and the second pass is encoded based -on those statistics. If you are short on disk space or don't want the -extra disk wear from writing the file twice, you can use -o /dev/null -during the first pass. However, sometimes it is beneficial to watch -the first-pass file before beginning the second pass to make sure -nothing went wrong in the encoding. - -Next, an example using Xvid instead of libavcodec: - - Encoding from an existing AVI file - 500 kbit/sec MPEG-4 video - Copying the existing audio stream unmodified - - mencoder foo.avi -vf scale=320:240 -mc 0 -oac copy -ovc xvid \ - -xvidencopts bitrate=400:pass=1 - - mencoder foo.avi -vf scale=320:240 -mc 0 -oac copy -ovc xvid \ - -xvidencopts bitrate=400:pass=2 - -The options used are slightly different, but the process is otherwise -the same. diff --git a/DOCS/tech/encoding-tips.txt b/DOCS/tech/encoding-tips.txt deleted file mode 100644 index 8891bdc20a..0000000000 --- a/DOCS/tech/encoding-tips.txt +++ /dev/null @@ -1,725 +0,0 @@ - -Some important URLs: -~~~~~~~~~~~~~~~~~~~~ -http://mplayerhq.hu/~michael/codec-features.html <- lavc vs. divx5 vs. xvid -http://www.ee.oulu.fi/~tuukkat/mplayer/tests/rguyom.ath.cx/ <- lavc benchmarks, options -http://ffdshow.sourceforge.net/tikiwiki/tiki-view_articles.php <- lavc for win32 :) -http://www.bunkus.org/dvdripping4linux/index.html <- a nice tutorial -http://forum.zhentarim.net/viewtopic.php?p=237 <- lavc option comparison -http://www.ee.oulu.fi/~tuukkat/mplayer/tests/readme.html <- series of benchmarks -http://thread.gmane.org/gmane.comp.video.mencoder.user/1196 <- free codecs shoutout and recommended encoding settings - - -================================================================================ - - -FIXING A/V SYNC WHEN ENCODING - -I know this is a popular topic on the list, so I thought I'd share a -few comments on my experience fixing a/v sync. As everyone seems to -know, mencoder unfortunately doesn't have a -delay option. But that -doesn't mean you can't fix a/v sync. There are a couple ways to still -do it. - -In example 1, we'll suppose you want to re-encode the audio anyway. -This will be essential if your source audio isn't mp3, e.g. for DVD's -or nasty avi files with divx/wma audio. This approach makes things -much easier. - -Step 1: Dump the audio with mplayer -ao pcm -nowaveheader. There are -various options that can be used to speed this up, most notably -vo -null, -vc null, and/or -hardframedrop. -benchmark also seemed to help -in the past. :) - -Step 2: Figure out what -delay value syncs the audio right in mplayer. -If this number is positive, use a command like the following: - -dd if=audiodump.wav bs=1764 skip=[delay] | lame -x - out.mp3 - -where [delay] is replaced by your delay amount in hundredths of a -second (1/10 the value you use with mplayer). Otherwise, if delay is -negative, use a command like this: - -( dd if=/dev/zero bs=1764 skip=[delay] ; cat audiodump.wav ) | lame -x - out.mp3 - -Don't include the minus (-) sign in delay. Also, keep in mind you'll -have to change the 1764 number and provide additional options to lame -if your audio stream isn't 44100/16bit/little-endian/stereo. - -Step 3: Use mencoder to remux your new mp3 file with the movie: - -mencoder -audiofile out.mp3 -oac copy ... - -You can either copy video as-is (with -ovc copy) or re-encode it at -the same time you merge in the audio like this. - -Finally, as a variation on this method (makes things a good bit faster -and doesn't use tons of temporary disk space) you can merge steps 1 -and 2 by making a named pipe called "audiodump.wav" (type mkfifo -audiodump.wav) and have mplayer write the audio to it at the same time -you're running lame to encode. - -Now for example 2. This time we won't re-encode audio at all. Just -dump the mp3 stream from the avi file with mplayer -dumpaudio. Then, -you have to cut and paste the raw mp3 stream a bit... - -If delay is negative, things are easier. Just use lame to encode -silence for the duration of delay, at the same samplerate and -samplesize used in your avi file. Then, do something like: - -cat silence.mp3 stream.dump > out.mp3 -mencoder -audiofile out.mp3 -oac copy ... - -On the other hand, if delay is positive, you'll need to crop off part -of the mp3 from the beginning. If it's (at least roughly) CBR this is -easy -- just take off the first (bitrate*delay/8) bytes of the file. -You can use the excellent dd tool, or just your favorite -binary-friendly text editor to do this. Otherwise, you'll have to -experiment with cutting off different amounts. You can test with -mplayer -audiofile before actually spending time remuxing/encoding -with mencoder to make sure you cut the right amount. - -I hope this has all been informative. If anyone would like to clean -this message up a bit and make it into part of the docs, feel free. Of -course mencoder should eventually just get -delay. :) - -Rich - - -================================================================================ - - -ENCODING QUALITY - OR WHY AUTOMATISM IS BAD. - -Hi everyone. - -Some days ago someone suggested adding some preset options to mencoder. -At that time I replied 'don't do that', and now I decided to elaborate -on that. - -Warning: this is rather long, and it involves mathematics. But if you -don't want to bother with either then why are you encoding in the -first place? Go do something different! - -The good news is: it's all about the bpp (bits per pixel). - -The bad news is: it's not THAT easy ;) - -This mail is about encoding a DVD to MPEG4. It's about the video -quality, not (primarily) about the audio quality or some other fancy -things like subtitles. - -The first step is to encode the audio. Why? Well if you encode the -audio prior to the video you'll have to make the video fit onto one -(or two) CD(s). That way you can use oggenc's quality based encoding -mode which is much more sophisticated than its ABR based mode. - -After encoding the audio you have a certain amount of space left to -fill with video. Let's assume the audio takes 60M (no problem with -Vorbis), and you aim at a 700M CD. This leaves you 640M for the video. -Let's further assume that the video is 100 minutes or 6000 seconds -long, encoded at 25fps (those nasty NTSC fps values give me -headaches. Adjust to your needs, of course!). This leaves you with -a video bitrate of: - - $videosize * 8 -$videobitrate = -------------- - $length * 1000 - -$videosize in bytes, $length in seconds, $videobitrate in kbit/s. -In my example I end up with $videobitrate = 895. - -And now comes the question: how do I chose my encoding parameters -so that the results will be good? First let's take a look at a -typical mencoder line: - -mencoder dvd://1 -o /dev/null -oac copy -ovc lavc \ - -lavcopts vcodec=mpeg4:vbitrate=1000:vhq:vqmin=2:\ - vlelim=-4:vcelim=9:lumi_mask=0.05:dark_mask=0.01:vpass=1 \ - -vf crop=716:572:2:2,scale=640:480 - -Phew, all those parameters! Which ones should I change? NEVER leave -out 'vhq'. Never ever. 'vqmin=2' is always good if you aim for sane -settings - like 'normal length' movies on one CD, 'very long movies' -on two CDs and so on. vcodec=mpeg4 is mandatory. - -The 'vlelim=-4:vcelim=9:lumi_mask=0.05:dark_mask=0.01' are parameters -suggested by D Richard Felker for non-animated movies, and they -improve quality a bit. - -But the two things that have the most influence on quality are -vbitate and scale. Why? Because both together tell the codec how -many bits it may spend on each frame for each bit: and this is -the 'bpp' value (bits per pixel). It's simply defined as - - $videobitrate * 1000 -$bpp = ----------------------- - $width * $height * $fps - -I've attached a small Perl script that calculates the $bpp for -a movie. You'll have to give it four parameters: -a) the cropped but unscaled resolution (use '-vf cropdetect'), -b) the encoded aspect ratio. All DVDs come at 720x576 but contain -a flag that tells the player wether it should display the DVD at -an aspect ratio of 4/3 (1.333) or at 16/9 (1.777). Have a look -at mplayer's output - there's something about 'prescaling'. That's -what you are looking for. -c) the video bitrate in kbit/s and -d) the fps. - -In my example the command line and calcbpp.pl's output would look -like this (warning - long lines ahead): - -mosu@anakin:~$ ./calcbpp.pl 720x440 16/9 896 25 -Prescaled picture: 1023x440, AR 2.33 -720x304, diff 5, new AR 2.37, AR error 1.74% scale=720:304 bpp: 0.164 -704x304, diff -1, new AR 2.32, AR error 0.50% scale=704:304 bpp: 0.167 -688x288, diff 8, new AR 2.39, AR error 2.58% scale=688:288 bpp: 0.181 -672x288, diff 1, new AR 2.33, AR error 0.26% scale=672:288 bpp: 0.185 -656x288, diff -6, new AR 2.28, AR error 2.17% scale=656:288 bpp: 0.190 -640x272, diff 3, new AR 2.35, AR error 1.09% scale=640:272 bpp: 0.206 -624x272, diff -4, new AR 2.29, AR error 1.45% scale=624:272 bpp: 0.211 -608x256, diff 5, new AR 2.38, AR error 2.01% scale=608:256 bpp: 0.230 -592x256, diff -2, new AR 2.31, AR error 0.64% scale=592:256 bpp: 0.236 -576x240, diff 8, new AR 2.40, AR error 3.03% scale=576:240 bpp: 0.259 -560x240, diff 1, new AR 2.33, AR error 0.26% scale=560:240 bpp: 0.267 -544x240, diff -6, new AR 2.27, AR error 2.67% scale=544:240 bpp: 0.275 -528x224, diff 3, new AR 2.36, AR error 1.27% scale=528:224 bpp: 0.303 -512x224, diff -4, new AR 2.29, AR error 1.82% scale=512:224 bpp: 0.312 -496x208, diff 5, new AR 2.38, AR error 2.40% scale=496:208 bpp: 0.347 -480x208, diff -2, new AR 2.31, AR error 0.85% scale=480:208 bpp: 0.359 -464x192, diff 7, new AR 2.42, AR error 3.70% scale=464:192 bpp: 0.402 -448x192, diff 1, new AR 2.33, AR error 0.26% scale=448:192 bpp: 0.417 -432x192, diff -6, new AR 2.25, AR error 3.43% scale=432:192 bpp: 0.432 -416x176, diff 3, new AR 2.36, AR error 1.54% scale=416:176 bpp: 0.490 -400x176, diff -4, new AR 2.27, AR error 2.40% scale=400:176 bpp: 0.509 -384x160, diff 5, new AR 2.40, AR error 3.03% scale=384:160 bpp: 0.583 -368x160, diff -2, new AR 2.30, AR error 1.19% scale=368:160 bpp: 0.609 -352x144, diff 7, new AR 2.44, AR error 4.79% scale=352:144 bpp: 0.707 -336x144, diff 0, new AR 2.33, AR error 0.26% scale=336:144 bpp: 0.741 -320x144, diff -6, new AR 2.22, AR error 4.73% scale=320:144 bpp: 0.778 - -A word for the $bpp. For a fictional movie which is only black and -white: if you have a $bpp of 1 then the movie would be stored -uncompressed :) For a real life movie with 24bit color depth you -need compression of course. And the $bpp can be used to make the -decision easier. - -As you can see the resolutions suggested by the script are all -dividable by 16. This will make the aspect ratio slightly wrong, -but no one will notice. - -Now if you want to decide which resolution (and scaling parameters) -to chose you can do that by looking at the $bpp: - -< 0.10: don't do it. Please. I beg you! -< 0.15: It will look bad. -< 0.20: You will notice blocks, but it will look ok. -< 0.25: It will look really good. -> 0.25: It won't really improve visually. -> 0.30: Don't do that either - try a bigger resolution instead. - -Of course these values are not absolutes! For movies with really lots -of black areas 0.15 may look very good. Action movies with only high -motion scenes on the other hand may not look perfect at 0.25. But these -values give you a great idea about which resolution to chose. - -I see a lot of people always using 512 for the width and scaling -the height accordingly. For my (real-world-)example this would be -simply a waste of bandwidth. The encoder would probably not even -need the full bitrate, and the resulting file would be smaller -than my targetted 700M. - -After encoding you'll do your 'quality check'. First fire up the movie -and see whether it looks good to you or not. But you can also do a -more 'scientific' analysis. The second Perl script I attached counts -the quantizers used for the encoding. Simply call it with - -countquant.pl < divx2pass.log - -It will print out which quantizer was used how often. If you see that -e.g. the lowest quantizer (vqmin=2) gets used for > 95% of the frames -then you can safely increase your picture size. - -> The "counting the quantesizer"-thing could improve the quality of -> full automated scripts, as I understand ? - -Yes, the log file analysis can be used be tools to automatically adjust -the scaling parameters (if you'd do that you'd end up with a three-pass -encoding for the video only ;)), but it can also provide answers for -you as a human. From time to time there's a question like 'hey, -mencoder creates files that are too small! I specified this bitrate and -the resulting file is 50megs short of the target file size!'. The -reason is probably that the codec already uses the minimum quantizer -for nearly all frames so it simply does not need more bits. A quick -glance at the distribution of the quantizers can be enlightening. - -Another thing is that q=2 and q=3 look really good while the 'bigger' -quantizers really lose quality. So if your distribution shows the -majority of quantizers at 4 and above then you should probably decrease -the resolution (you'll definitly see block artefacts). - - -Well... Several people will probably disagree with me on certain -points here, especially when it comes down to hard values (like the -$bpp categories and the percentage of the quantizers used). But -the idea is still valid. - -And that's why I think that there should NOT be presets in mencoder -like the presets lame knows. 'Good quality' or 'perfect quality' are -ALWAYS relative. They always depend on a person's personal preferences. -If you want good quality then spend some time reading and - more -important - understanding what steps are involved in video encoding. -You cannot do it without mathematics. Oh well, you can, but you'll -end up with movies that could certainly look better. - -Now please shoot me if you have any complaints ;) - --- - ==> Ciao, Mosu (Moritz Bunkus) - -=========== -ANOTHER APPROACH: BITS PER BLOCK: - -> $videobitrate * 1000 -> $bpp = ----------------------- -> $width * $height * $fps - -Well, I came to similar equation going through different route. Only I -didn't use bits per pixel, in my case it was bits per block (BPB). The block -is 16x16 because lots of software depends on video width/height being -divisable by 16. And because I didn't like this 0.2 bit per pixel, when -bit is quite atomic ;) - -So the equation was something like: - - bitrate -bpb = ----------------- - fps * ((width * height) / (16 * 16)) - -(width and height are from destination video size, and bitrate is in -bits (i.e. 900kbps is 900000)) - -This way it apeared that the minimum bits per block is ~40, very -good results are with ~50, and everything above 60 is a waste of bandwidth. -And what's actually funny is that it was independent of codec used. The -results were exactly the same, whether I used DIV3 (with tricky nandub's -magick), ffmpeg odivx, DivX5 on Windows or Xvid. - -Surprisingly there is one advantage of using nandub-DIV3 for bitrate -starved encoding: ringing almost never apears this way. - -But I also found out, that the quality/BPB isn't constant for -drastically different resolutions. Smaller picture (like MPEG1 sizes) -need more BPB to look good than say typical MPEG2 resolutions. - -Robert - - -=========== -DON'T SCALE DOWN TOO MUCH - -Sometimes I found that encoding to y-scaled only DVD qualty (ie 704 x -288 for a 2.85 film) gives better visual quality than a scaled-down -version even if the quantizers are significantly higher than for the -scaled-down version. -Keep in mind that blocs, fuzzy parts and generaly mpeg artefacts in a -704x288 image will be harder to spot in full-screen mode than on a -512x208 image. In fact I've see example where the same movie looks -better compressed to 704x288 with an average weighted quantizer of -~3 than the same movie scaled to 576x240 with an average weighted -quantizer of 2.4. -Btw, a print of the weighted average quantizer would be nice in -countquant.pl :) - -Another point in favor of not trying to scale down too much : on hard -scaled-down movies, the MPEG codec will need to compress relatively -high frequencies rather than low frequencies and it doesn't like that -at all. You will see less and less returns while you scale down and -scale down again in desesperate need of some bandwidth :) - -In my experience, don't try to go below a width of 576 without closely -watching what's going on. - --- -Rémi - -=========== -TIPS FOR ENCODING - -That being said, with video you have some tradeoffs you can make. Most -people seem to encode with really basic options, but if you play with -single coefficient elimination and luma masking settings, you can save lots -of bits, resulting in lower quantizers, which means less blockiness and -less ugly noise (ringing) around sharp borders. The tradeoff, however, is -that you'll get some "muddiness" in some parts of the image. Play around -with the settings and see for yourself. The options I typically use for -(non-animated) movies are: - -vlelim=-4 -vcelim=9 -lumi_mask=0.05 -dark_mask=0.01 - -If things look too muddy, making the numbers closer to 0. For anime and -other animation, the above recommendations may not be so good. - -Another option that may be useful is allowing four motion vectors per -macroblock (v4mv). This will increase encoding time quite a bit, and -last I checked it wasn't compatible with B frames. AFAIK, specifying -v4mv should never reduce quality, but it may prevent some old junky -versions of DivX from decoding it (can anyone conform?). Another issue -might be increased cpu time needed for decoding (again, can anyone -confirm?). - -To get more fair distribution of bits between low-detail and -high-detail scenes, you should probably try increasing vqcomp from the -default (0.5) to something in the range 0.6-0.8. - -Of course you also want to make sure you crop ALL of the black border and -any half-black pixels at the edge of the image, and make sure the final -image dimensions after cropping and scaling are multiples of 16. Failing to -do so will drastically reduce quality. - -Finally, if you can't seem to get good results, you can try scaling the -movie down a bit smaller or applying a weak gaussian blur to reduce the -amount of detail. - -Now, my personal success story! I just recently managed to fit a beautiful -encode of Kundun (well over 2 hours long, but not too many high-motion -scenes) on one cd at 640x304, with 66 kbit/sec abr ogg audio, using the -options I described above. So, IMHO it's definitely possible to get very -good results with libavcodec (certainly MUCH better than all the idiot -"release groups" using DivX3 make), as long as you take some time to play -around with the options. - - -Rich - -============ -ABOUT VLELIM, VCELIM, LUMI_MASK AND DARK_MASK PART I: LUMA & CHROMA - - -The l/c in vlelim and vcelim stands for luma (brightness plane) and chroma -(color planes). These are encoded separately in all mpeg-like algorithms. -Anyway, the idea behind these options is (at least from what I understand) -to use some good heuristics to determine when the change in a block is less -than the threshold you specify, and in such a case, to just encode the -block as "no change". This saves bits and perhaps speeds up encoding. Using -a negative value for either one means the same thing as the corresponding -positive value, but the DC coefficient is also considered. Unfortunately -I'm not familiar enough with the mpeg terminology to know what this means -(my first guess would be that it's the constant term from the DCT), but it -probably makes the encoder less likely to apply single coefficient -elimination in cases where it would look bad. It's presumably recommended -to use negative values for luma (which is more noticable) and positive for -chroma. - -The other options -- lumi_mask and dark_mask -- control how the quantizer -is adjusted for really dark or bright regions of the picture. You're -probably already at least a bit familiar with the concept of quantizers -(qscale, lower = more precision, higher quality, but more bits needed to -encode). What not everyone seems to know is that the quantizer you see -(e.g. in the 2pass logs) is just an average for the whole frame, and lower -or higher quantizers may in fact be used in parts of the picture with more -or less detail. Increasing the values of lumi_mask and dark_mask will cause -lavc to aggressively increase the quantizer in very dark or very bright -regions of the picture (which are presumably not as noticable to the human -eye) in order to save bits for use elsewhere. - -Rich - -=================== -ABOUT VLELIM, VCELIM, LUMI_MASK AND DARK_MASK PART II: VQSCALE - -OK, a quick explanation. The quantizer you set with vqscale=N is the -per-frame quantizer parameter (aka qp). However, with mpeg4 it's -allowed (and recommended!) for the encoder to vary the quantizer on a -per-macroblock (mb) basis (as I understand it, macroblocks are 16x16 -regions composed of 4 8x8 luma blocks and 2 8x8 chroma blocks, u and -v). To do this, lavc scores each mb with a complexity value and -weights the quantizer accordingly. However, you can control this -behavior somewhat with scplx_mask, tcplx_mask, dark_mask, and -lumi_mask. - -scplx_mask -- raise quantizer on mb's with lots of spacial complexity. -Spacial complexity is measured by variance of the texture (this is -just the actual image for I blocks and the difference from the -previous coded frame for P blocks). - -tcplx_mask -- raise quantizer on mb's with lots of temporal -complexity. Temporal complexity is measured according to motion -vectors. - -dark_mask -- raise quantizer on very dark mb's. - -lumi_mask -- raise quantizer on very bright mb's. -Somewhere around 0-0.15 is a safe range for these values, IMHO. You -might try as high as 0.25 or 0.3. You should probably never go over -0.5 or so. - -Now, about naq. When you adjust the quantizers on a per-mb basis like -this (called adaptive quantization), you might decrease or (more -likely) increase the average quantizer used, so that it no longer -matches the requested average quantizer (qp) for the frame. This will -result in weird things happening with the bitrate, at least from my -experience. What naq does is "normalize adaptive quantization". That -is, after the above masking parameters are applied on a per-mb basis, -the quantizers of all the blocks are rescaled so that the average -stays fixed at the desired qp. - -So, if I used vqscale=4 with naq and fairly large values for the -masking parameters, I might be likely to see lots of frames using -qscale 2,3,4,5,6,7 across different macroblocks as needed, but with -the average sticking around 4. However, I haven't actually tested such -a setup yet, so it's just speculation right now. - -Have fun playing around with it. - -Rich - - -================================================================================ - - -TIPS FOR ENCODING OLD BLACK & WHITE MOVIES: - -I found myself that 4:3 B&W old movies are very hard to compress well. In -addition to the 4:3 aspect ratio which eats lots of bits, those movies are -typically very "noisy", which doesn't help at all. Anyway : - -> After a few tries I am -> still a little bit disappointed with the video quality. Since it is a -> "dark" movies, there is a lot of black on the pictures, and on the -> encoded avi I can see a lot of annoying "mpeg squares". I am using -> avifile codec, but the best I think is to give you the command line I -> used to encode a preview of the result: - -> -> First pass: -> mencoder TITLE01-ANGLE1.VOB -oac copy -ovc lavc -lavcopts -> vcodec=mpeg4:vhq:vpass=1:vbitrate=800:keyint=48 -ofps 23.976 -npp lb -> -ss 2:00 -endpos 0:30 -vf scale -zoom -xy 640 -o movie.avi - -1) keyint=48 is way too low. The default value is 250, this is in *frames* -not seconds. Keyframes are significantly larger than P or B frames, so the -less keyframes you have, better the overall movie will be. (huh, like Yoda -I speak ;). Try keyint=300 or 350. Don't go beyond that if you want -relatively precise seeking. - -2) you may want to play with vlelim and vcelim options. This can gives you -a significant "quality" boost. Try one of these couples : - -vlelim=-2:vcelim=3 -vlelim=-3:vcelim=5 -vlelim=-4:vcelim=7 -(and yes, there's a minus) - -3) crop & rescale the movie before passing it to the codec. First crop the -movie to not encode black bars if there's any. For a 1h40mn movie -compressed to a 700 MB file, I would try something between 512x384 and -480x320. Don't go below that if you want something relatively sharp when -viewed fullscreen. - -4) I would recommend using the Ogg Vorbis audio codec with the .ogm -container format. Ogg Vorbis compress audio better than MP3. On a typical -old, mono-only audio stream, a 45 kbits/s Vorbis stream is ok. How to -extract & compress an audio stream from a ripped DVD (mplayer dvd://1 --dumpstream) : - -rm -f audiodump.pcm ; mkfifo -m 600 audiodump.pcm -mplayer -quiet -vc null -vo null -aid 128 -ao pcm -nowaveheader stream.dump & -oggenc --raw --raw-bits=16 --raw-chan=2 --raw-rate=48000 -q 1 -o audio-us.ogg -+audiodump.pcm & -wait - -For a nice set of utilities to manager the .ogm format, see Moritz Bunkus' -ogmtools (google is your friend). - -5) use the "v4mv" option. This could gives you a few more bits at the -expense of a slightly longer encoding. This is a "lossless" option, I mean -with this option you don't throw away some video information, it just -selects a more precise motion estimation method. Be warned that on some -very un-typical scenes this option may gives you a longer file than -without, although it's very rare and on a whole film I think it's always a -win. - -6) you can try the new luminance & darkness masking code. Play -with the "lumi_mask" and "dark_mask" options. I would recommend using -something like : -lumi_mask=0.07:dark_mask=0.10:naq: -lumi_mask=0.10:dark_mask=0.12:naq: -lumi_mask=0.12:dark_mask=0.15:naq -lumi_mask=0.13:dark_mask=0.16:naq: -Be warned that these options are really experimental and the result -could be very good or very bad depending on your visualization device -(computer CRT, TV or TFT screen). Don't push too hard these options. - -> Second pass: -> the same with vpass=2 - -7) I've found that lavc gives better results when the first pass is done -with "vqscale=2" instead of a target bitrate. The statistics collected -seems to be more precise. YMMV. - -> I am new to mencoder, so please tell me any idea you have even if it -> obvious. I also tried the "gray" option of lavc, to encode B&W only, -> but strangely it gives me "pink" squares from time to time. - -Yes, I've seen that too. Playing the resulting file with "-lavdopts gray" -fix the problem but it's not very nice ... - -> So if you could tell me what option of mencoder or lavc I should be -> looking at to lower the number of "squares" on the image, it would be -> great. The version of mencoder i use is 0.90pre8 on a macos x PPC -> platform. I guess I would have the same problem by encoding anime -> movies, where there are a lot of region of the image with the same -> color. So if you managed to solve this problem... - -You could also try the "mpeg_quant" flag. It selects a different set of -quantizers and produce somewhat sharper pictures and less blocks on large -zones with the same or similar luminance, at the expense of some bits. - -> This is completely off topic, but do you know how I can create good -> subtitles from vobsub subtitles ? I checked the -dumpmpsub option of -> mplayer, but is there a way to do it really fast (ie without having to -> play the whole movie) ? - -I didn't find a way under *nix to produce reasonab