.:: h264enc FAQ/Doc ::.
Last updated: 01-July-2009
The h264enc package includes a man page which you should read carefully. The package also includes a README.encoding file which is located in the doc directory and describes the encoding process in depth. Depending on the Linux distro you are using, the doc directory is usually located in /usr/share/doc/h264enc or /usr/share/doc/packages/h264enc. If you have installed h264enc using the install script included in the tgz compressed package, then this directory is located in /usr/local/share/doc/h264enc
h264enc is an interactive script. What this means is that it asks you questions and you have to answer them with either 'y' or 'n'. However, if you don't want to use something, then instead of always providing 'n' as an answer, you can just hit Enter.
- Why a shell script?
Well, this has a lot to do with the history of h264enc. Some years ago, I was tired of always providing the MEncoder parameters on the command line whenever I wanted to encode something, so I needed a quick and dirty fix for that. And what is more faster to write than a shell script? There are other reasons though. Shell scripts are very easy to write, are less prone to bugs and are small in their sizes - not that anyone cares though. h264enc was for about 1 year in private use before I made the decision to go public with it. I'm also more comfortable with scripting than with C or C++ coding and somehow I love their simplicity. Yes, shell scripting can be very restrictive when you need to do something (very) complex but in the case of h264enc, nothing really complex is done. It's basically a "collector" script for user input enhanced with automatic functions to retrieve information from DVDs and do some other stuff like audio encoding using extrenal encoders and container muxing. One also has to ask himself about what a GUI does for 95% of the encoding process? The simple answer to this is that a GUI does absolutely nothing. It just sits there in memory displaying a fancy progress bar and that's it. So there you go. h264enc is just a stupid script which happens to work quite well for me, and I hope for others too...
- Input
h264enc supports as input single video files, a directory with video files, DVDs and (S)VCDs. For DVDs, one is presented with a menu where one can choose to encode straight from a DVD drive, from an ISO image or from a VIDEO_TS folder. For video files, one can either choose to encode a single file or a bunch of files which are inside a directory. If you choose to encode a directory with video files, you have to configure at least one video file. All the chosen settings for that video file will automatically apply to the others too so be carefull when choosing the settings. When encoding a directory with video files, h264enc operates in full batch mode. Remuxing of all the encoded files to the MKV/MP4/OGM/TS containers is also supported. One thing I will not recommend when using full batch mode, is copying the audio stream of all files. Unless you're absolutely sure that all video files have the same audio format, you're better off encoding the audio instead to a format which is supported by the chosen container(s).
- Output
h264enc supports outputting to the AVI, MKV, MP4, OGM and TS containers. The standard output container of h264enc is AVI which later on is used to remux it to the above mentioned containers using mkvmerge, MP4Box, ogmmerge and tsMuxeR respectively. Further, h264enc is able to create a Blu-ray and AVCHD disc structure if tsMuxeR is available on the user's system.
Reasons why h264enc uses AVI as default container:
h264enc supports automatic metadata tagging for the MKV/MP4/OGM/TS containers. The following is currently supported:
h264enc supports 1-pass, 2-pass, 3-pass and fixed-quant/constant rate factor encodings. During encoding configuration, it is also possible to store your settings to a file which can be used as a (simple) batch file. h264enc is designed around a powerful presets system and currently has 58 presets, including presets for portable devices like Apple iPod, Apple iPhone, AppleTV, Blackberry Bold 9000, Nokia S60, Archos 605/5, Sony PSP, Sony PS3, Microsoft XBOX360 and Microsoft Zune. If you use the standard PC presets, do not go above the EHQ preset unless you're prepared to wait a long time (sometimes days, depending on the content and the computer you're doing the encoding on). For the more experienced user, h264enc also supports writing your own preset files which can be loaded into the script. There is an example skeleton preset file called 'preset.cfg' located in the 'doc' directory of the h264enc package which can be used as a starting point in writing your own presets. The file also explains which x264 options are supported and which not.
When you're done with your own preset file, you can easily load it with: h264enc -2p -p cp /path/to/preset/file.cfg
One can also pause the encoding process with CTRL+Z and continue later on by typing fg in the terminal.
- Subtitles
h264enc supports subtitles for video file, (S)VCD and DVD encodings. For video files and (S)VCDs, one has the choice of hardcoding an external subtitle into the video or importing up to three subtitles into the MKV/MP4/OGM containers. Subtitles are also supported for batch encoding of a directory with video files.
For DVD encodings, the script supports hardcoding a DVD subtitle into the movie, importing up to three external subtitles into the MKV/MP4/OGM containers, hardcoding an external subtitle into the movie or dumping up to three subtitles from the DVD to disk which then can be optionally imported into the MKV and/or MP4 container.
- Video filters
The script has a very mature support for various pre/postprocessing video filters. At the moment, it supports the following video filters:
Currently, four audio filters are supported: volume normalization (volnorm), the volume filter, resample and lavcresample.
- Audio codecs
At the moment, h264enc supports 6 different audio codecs: MP3, AC3, LC-AAC/HE-AACv1/HE-AACv2, Vorbis, FLAC and PCM. In addition, h264enc also supports the COPY and NOSOUND formats of MEncoder. For LC-AAC audio, h264enc supports two audio encoders; FAAC and neroAacEnc. For HE-AAC audio (also known as AAC+) one can either use the neroAacEnc or aacplusenc encoder. For Vorbis audio, oggenc is required. FLAC audio requires the flac encoder as doing it through MEncoder is terribly broken. The current audio code is easily extensible, thanks to using arrays, and in theory one can add support for as many audio tracks as he wishes for. For DVD encodings, h264enc supports up to three audio tracks. Things that can be set per track include:
- Miscellaneous
Other things that are supported include...
The h264enc package includes a man page which you should read carefully. The package also includes a README.encoding file which is located in the doc directory and describes the encoding process in depth. Depending on the Linux distro you are using, the doc directory is usually located in /usr/share/doc/h264enc or /usr/share/doc/packages/h264enc. If you have installed h264enc using the install script included in the tgz compressed package, then this directory is located in /usr/local/share/doc/h264enc
h264enc is an interactive script. What this means is that it asks you questions and you have to answer them with either 'y' or 'n'. However, if you don't want to use something, then instead of always providing 'n' as an answer, you can just hit Enter.
- Why a shell script?
- Input
- Output
- Tagging
- Encoding
- Subtitles
- Video filters
- Audio filters
- Audio codecs
- Miscellaneous
- Pros / Cons
- Why a shell script?
Well, this has a lot to do with the history of h264enc. Some years ago, I was tired of always providing the MEncoder parameters on the command line whenever I wanted to encode something, so I needed a quick and dirty fix for that. And what is more faster to write than a shell script? There are other reasons though. Shell scripts are very easy to write, are less prone to bugs and are small in their sizes - not that anyone cares though. h264enc was for about 1 year in private use before I made the decision to go public with it. I'm also more comfortable with scripting than with C or C++ coding and somehow I love their simplicity. Yes, shell scripting can be very restrictive when you need to do something (very) complex but in the case of h264enc, nothing really complex is done. It's basically a "collector" script for user input enhanced with automatic functions to retrieve information from DVDs and do some other stuff like audio encoding using extrenal encoders and container muxing. One also has to ask himself about what a GUI does for 95% of the encoding process? The simple answer to this is that a GUI does absolutely nothing. It just sits there in memory displaying a fancy progress bar and that's it. So there you go. h264enc is just a stupid script which happens to work quite well for me, and I hope for others too...
- Input
h264enc supports as input single video files, a directory with video files, DVDs and (S)VCDs. For DVDs, one is presented with a menu where one can choose to encode straight from a DVD drive, from an ISO image or from a VIDEO_TS folder. For video files, one can either choose to encode a single file or a bunch of files which are inside a directory. If you choose to encode a directory with video files, you have to configure at least one video file. All the chosen settings for that video file will automatically apply to the others too so be carefull when choosing the settings. When encoding a directory with video files, h264enc operates in full batch mode. Remuxing of all the encoded files to the MKV/MP4/OGM/TS containers is also supported. One thing I will not recommend when using full batch mode, is copying the audio stream of all files. Unless you're absolutely sure that all video files have the same audio format, you're better off encoding the audio instead to a format which is supported by the chosen container(s).
- Output
h264enc supports outputting to the AVI, MKV, MP4, OGM and TS containers. The standard output container of h264enc is AVI which later on is used to remux it to the above mentioned containers using mkvmerge, MP4Box, ogmmerge and tsMuxeR respectively. Further, h264enc is able to create a Blu-ray and AVCHD disc structure if tsMuxeR is available on the user's system.
Reasons why h264enc uses AVI as default container:
- Historical: h264enc is a modified clone of the much older xvidenc script which uses AVI. Their codebase is almost identical, with the exception that h264enc uses specific x264 MEncoder settings and has a bit more audio code for the portable device presets.
- Practical: given the amount of audio and video filters the script supports, it's much easier for me to work with a default container like AVI. Maybe at some point I will remove AVI support... who knows? ;)
- MEncoder has one of the most robust AVI support out of all encoders I have encountered. It was primarely designed to deal with
broken AVI files, hence its robust AVI implementation. If it was possible to encode a walrus, MEncoder will probably be able to store
it in an AVI. This, however, does not justify that H.264 in AVI is a good thing. In fact, it is bad due to the nature of how
H.264 video handles frames and how AVI stores them. In contrary to popular belives though, H.264 video in AVI is not that bad as one might
think. I have read on various places where people claim that if you encode to H.264 and store it in an AVI, you will lose all B-Frames.
This is certainly not the case! If it was, you'd completely lose decoding of non-keyframes and your file will be unwatchable! The problem
with H.264 video in AVI arises when one uses B-Frames, especially Pyramidal B-Frames (the b_pyramid option in MEncoder) which requires some
ugly hacks to work correctly, and even then it isn't optimal. But then again no one complains when using MPEG4 ASP (Xvid, DivX, etc) in AVI, which requires the exactly
same nasty hacks when using B-Frames, even more so if those are packed.
Much of the misconceptions about AVI come from people who are not familiar with the official Microsoft specs of the AVI container. Throw into the game the various hacks added over the years to AVI which are not included in the official spec, and you have one big mess about what and what isn't supported/allowed/good/bad in AVI.
More information about some of the misconceptions and believes about the AVI container, can be found here, here and here.
h264enc supports automatic metadata tagging for the MKV/MP4/OGM/TS containers. The following is currently supported:
- Video/movie title metadata (supported by: all input types - containers: MKV/MP4/OGM)
- Import of chapters metadata (supported by: DVD encodings - containers: MKV/MP4/OGM)
- Import of jpeg/png cover art file (supported by: DVD/file/VCD - containers: MKV/MP4)
- Per track audio metadata (supported by: all input types - containers: MKV/MP4)
- Per track audio language metadata (supported by: DVD encodings - containers: MKV/MP4/TS)
h264enc supports 1-pass, 2-pass, 3-pass and fixed-quant/constant rate factor encodings. During encoding configuration, it is also possible to store your settings to a file which can be used as a (simple) batch file. h264enc is designed around a powerful presets system and currently has 58 presets, including presets for portable devices like Apple iPod, Apple iPhone, AppleTV, Blackberry Bold 9000, Nokia S60, Archos 605/5, Sony PSP, Sony PS3, Microsoft XBOX360 and Microsoft Zune. If you use the standard PC presets, do not go above the EHQ preset unless you're prepared to wait a long time (sometimes days, depending on the content and the computer you're doing the encoding on). For the more experienced user, h264enc also supports writing your own preset files which can be loaded into the script. There is an example skeleton preset file called 'preset.cfg' located in the 'doc' directory of the h264enc package which can be used as a starting point in writing your own presets. The file also explains which x264 options are supported and which not.
When you're done with your own preset file, you can easily load it with: h264enc -2p -p cp /path/to/preset/file.cfg
One can also pause the encoding process with CTRL+Z and continue later on by typing fg in the terminal.
- Subtitles
h264enc supports subtitles for video file, (S)VCD and DVD encodings. For video files and (S)VCDs, one has the choice of hardcoding an external subtitle into the video or importing up to three subtitles into the MKV/MP4/OGM containers. Subtitles are also supported for batch encoding of a directory with video files.
For DVD encodings, the script supports hardcoding a DVD subtitle into the movie, importing up to three external subtitles into the MKV/MP4/OGM containers, hardcoding an external subtitle into the movie or dumping up to three subtitles from the DVD to disk which then can be optionally imported into the MKV and/or MP4 container.
- Video filters
The script has a very mature support for various pre/postprocessing video filters. At the moment, it supports the following video filters:
- 11 software scaling filters (fast bilinear, bilinear, bicubic, experimental, nearest neighbor/point, area averaging, luma bicubic/chroma bilinear, gaussian, sinc, lanczos, natural bicubic spline)
- 5 deblock/dering postprocessing filters (spp, uspp, fspp, pp7, ha/va/dr)
- 5 denoise filters (denoise3d, hqdn3d, ow, tn, x264's internal denoiser)
- 1 (un)sharp mask/gaussian blur filter (unsharp)
- 10 different deinterlacers (lb, li, ci, md, fd, l5, yadif, tfields, mcdeint, kerndeint)
- 5 inverse telecine/3:2 pulldown filters (pullup, filmdint, ivtc, detc, telecine)
- Automatic brightness/contrast control filters
- 1 software equalizer filter (eq2)
- 1 interlacing filter (tinterlace combined with the phase filter)
- 2 frame rate conversion filters (filmdint, framestep)
Currently, four audio filters are supported: volume normalization (volnorm), the volume filter, resample and lavcresample.
- Audio codecs
At the moment, h264enc supports 6 different audio codecs: MP3, AC3, LC-AAC/HE-AACv1/HE-AACv2, Vorbis, FLAC and PCM. In addition, h264enc also supports the COPY and NOSOUND formats of MEncoder. For LC-AAC audio, h264enc supports two audio encoders; FAAC and neroAacEnc. For HE-AAC audio (also known as AAC+) one can either use the neroAacEnc or aacplusenc encoder. For Vorbis audio, oggenc is required. FLAC audio requires the flac encoder as doing it through MEncoder is terribly broken. The current audio code is easily extensible, thanks to using arrays, and in theory one can add support for as many audio tracks as he wishes for. For DVD encodings, h264enc supports up to three audio tracks. Things that can be set per track include:
- Per track audio codec and settings
- Per track audio channels
- Per track audio volume normalization
- Per track audio volume adjustments
- Per track audio resampling
- Miscellaneous
Other things that are supported include...
- Multiple formulas for video bitrate calculation for a target file size.
- Ability to export DVD chapters information which can be imported into the MKV/MP4/OGM containers.
- Extensive DVD information with the option to export it in plain-text, python, perl, ruby or xml format.
- Automatic meta-data addition for MKV/MP4/OGM/TS and cover art for MKV/MP4.
- Encoding of specific DVD chapters.
- Supports choosing the DVD angle.
- Auto-cropping (removing of black borders) with preview for DVDs, (S)VCDs and video files.
- Automatic calculation of Storage Aspect Ratio (SAR), Pixel Aspect Ratio (PAR) and total pixels from resolution.
- Ability to force the input aspec ratio.
- Colorspace conversion during scaling.
- Supports Bash completion.
- Ability to set the encoder priority level.
- Sample encoding to see the results before the real encoding starts.
- Supports dumping the contents of a DVD to an ISO image.
- Bits Per Pixel (bpp) and Bits Per Block (bpb) calculations for various resolutions.
- Written in a way to escape spaces in file names.
- Supports scanning the input video file for multiple audio and/or video streams.
- Sanity check which displays in a menu if the required programs are installed or missing.
- Pros
- Easy to use with sane defaults for almost everything
- Extensive video filters support which makes it good for dealing with different types of content
- Can operate in full batch encoding mode which is used to encode multiple video files with the same settings inside a given directory
- Supports up to three audio tracks for DVD encodings
- Enhanced with functions which gather audio/video info and present it in a clean and simple way
- Encoding can be made as simple or as complicated as the user wishes
- Presets-based. The user does not need to know/set complex encoder parameters
- Does not require the graphical X Window system, if you do not use crop preview and sample encoding
- Cons
- Interactive in nature. If you make one mistake, you'll have to start all over so make sure to read before typing!
- Not idiot-proof. Sometimes it requires that you know a bit about video processing
- Not a "one-click solution". If you're looking for this, then h264enc is not for you. I suggest trying out the more simple scripts like ripdvd and undvd
- Cannot automatically apply deinterlacing/inverse telecine due to the fact that MPlayer/MEncoder, currently, do not report if the content is interlaced or soft/hard telecined. Running a deinterlacer/pullup filter all the time on progressive content is bad for the quality and can slowdown the encoding process
- Probably a few more I can't think of now