.:: FAQ/Doc ::.
Last updated: 26 Jan 2016The 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. The script uses a configuration file stored in /home/username/.h264enc (a hidden directory) where the user can enable/disable many of the supported audio/video filters and containers. The config file also holds the paths to the programs needed by h264enc and a few other script related variables.
- Why a shell script?
- Encoding problems
- Input
- Output
- Tagging
- Encoding
- Encoding for Blu-ray/AVCHD
- Batch Encoding
- Subtitles
- Video filters
- Audio filters
- Audio codecs
- Audio Channels Downmix
- 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 external 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...
- Encoding problems
h264enc closely follows the development of MPlayer, MEncoder and x264. This means that when important options are added or removed in these programs, h264enc is usually updated very fast to support the changes. This can result in the script not working correctly with older versions of the above mentioned programs which usually results in MEncoder or MPlayer exiting with an error status. In this case, it is strongly recommended to get the latest available versions of these programs from Git(1) (for x264) and SVN(2) (for MPlayer/MEncoder) and compile them yourself if they are not yet available in your distro reporistory and you want to continue using the latest h264enc version. When h264enc is updated to support new options in any of these programs, it usually gets mentioned in the ChangeLog file so make sure to keep a close eye on it too.
(1) git clone git://git.videolan.org/x264.git
(2) svn checkout svn://svn.mplayerhq.hu/mplayer/trunk mplayer
- Input
h264enc supports as input single video files, a directory with video files, DVDs, unencrypted Blu-rays 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 directory. The same goes for Blu-ray. For video files, one can either choose to encode a single file or a bunch of files inside a directory. See the "Batch Encoding" section further below.
- 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 for about 80% 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 using Pyramidal B-Frames (the b_pyramid option in MEncoder/x264) which requires some
ugly hacks to work correctly, and even then it isn't optimal. But then again no one complains when using MPEG-4 ASP (Xvid, DivX, 3ivX, etc) in AVI,
which requires the exactly same nasty hacks when using B-Frames, even more so if those are packed. Further, for H.264 video, there really is
no standard way in AVI how to store B-Frames when using this video format while MPEG-4 ASP at least has a semi-standard way by packing
the B-Frames. Also, virtually all of the hardware devices out there that support H.264 will not support it if it's in an AVI. However,
there are a few Blu-ray players that do support H.264 video stored in an AVI. My LG BP620 Blu-ray player does so and I can confirm it
with 100% certainty.
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 (input: All - containers: MKV/MP4/OGM)
- Source type (input: All - containers: MKV)
- Video filters/Audio filters/Encoder/x264 parameters (input: All - containers: MKV)
- User specified Genre (input: File/DVD/BD/VCD - containers: MKV/MP4/OGM)
- User specified Year (input: File/DVD/BD/VCD - containers: MKV/MP4/OGM)
- Import of chapters (input: File/DVD/BD - containers: MKV/MP4/OGM)
- Import of jpeg/png cover art file (input: File/DVD/BD/VCD - containers: MKV/MP4)
- Per track audio codec (input: All - containers: MKV/MP4)
- Per track audio language (input: File/DVD - containers: MKV/MP4/TS/OGM)
- Subtitle language (input: File/DVD - containers: MKV/MP4/OGM)
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 55 presets, including presets for portable devices. 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) In most cases, anything higher than the EHQ preset will give you less than 1% improvement and can be consider a placebo as you won't be able to spot the difference unless you look with a magnifying glass.
In addition to the built-in script presets, h264enc also directly supports the native x264 presets, tunings and levels (see -h for more information). 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 for example.
One can also pause the encoding process with CTRL+Z and continue later on by typing fg in the terminal.
The script also uses a configuration file in its config directory located in one's /home/username/.h264enc directory. In there, one can enable/disable audio/video filters and containers and set a few other parameters. Disabling or enabling of filters and/or containers can be useful to many people as it gives them the ability to use only the things which they most often require. For example, if you never has a need for the interlace or sharpening filters, you can easily disable those in the config file, which also speeds up a bit passing through the script.
- Encoding for Blu-ray/AVCHD
h264enc has Blu-ray- and AVCHD-compliant presets (bd40, bdhq40, bd41, bdhq41, avchd and avchdhq) which you can use to output a compliant encode targeted at hardware players. As I only have one Blu-ray player (LG BP620), I cannot guarantee that the final encode will work flawlessly on all players but I did my best to fully comply with the Blu-ray and AVCHD specs. Note that the Blu-ray and AVCHD specs have very strict requirements with relation to resolution and FPS combinations and h264enc, currently, only gives a hint about what to use when encoding with one of these presets. It is highly recommended to get familiar with these restrictions before attempting to encode. For a quick overview on the Blu-ray resolution/FPS requirements, you can take a look at the wiki page. For AVCHD, click here or consult the wiki.
In order to create a compliant Blu-ray or AVCHD structure you need to have tsMuxeR installed on your system which you can get from the download page. When h264enc at the end of the configuration asks you if you want to convert the encode to Blu-ray or AVCHD, simply answer with 'y'. After all is done, you can write the result to a Blu-ray disc or, in case of AVCHD, to a DVD disc, using your favorite burning program.
- Batch Encoding
h264enc supports batch encoding. This is activated when you specify 'dir' (short for directory) as input. In batch encoding mode, you have to specify at least one video file from the directory you want to batch encode from. Everything you configure for that one video file will automatically apply to all video files in the directory, so it is important to be careful when configuring the encoding settings. Everything is supported while running in batch mode, except for multiple audio tracks. There are also a few corner cases where a specific option could be tricky and h264enc will warn you about it but not prevent you from using it, in case you know what you are doing.
Batch encoding is simply done by "cd'ing" to the directory to encode from and running a for loop on all files (directories inside the directory to encode from are ignored). Remuxing and tagging is also automatically done. Batch encoding is not directly executed inside h264enc but instead everything is stored in a new batch shell script and that shell script is called from inside h264enc. Also, batch encoding only works on files, so it is not possible yet to batch encode a bunch of VCDs/DVDs/Blu-rays.
- 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, hardcoding an embedded subtitle (for files) or importing virtually an unlimited amount of 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 external subtitles into the MKV/MP4/OGM containers, hardcoding an external subtitle into the movie or dumping subtitles from the DVD to disk which then can be optionally imported into the MKV and/or MP4 container.
Subtitles for Blu-rays are currently a bit problematic so the only options at the moment are to either hardcode an external subtitle or import subtitles into the MKV/MP4/OGM containers. It is not possible to dump subtitles from Blu-rays to disk yet or hardcode a subtitle from the Blu-ray itself. Further, if you want to create an AVCHD or Blu-ray structure, subtitles are not supported yet too.
- Video filters
The script has a very mature support for various pre/postprocessing video filters. At the moment, it supports the following video filters (many of which can be enabled/disabled in the config file):
- 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 noise filter (noise)
- 1 debanding filter (gradfun)
- 1 rotate filter
- 1 interlacing filter (tinterlace combined with the phase filter)
- 2 frame rate conversion filters (filmdint, framestep)
- 1 delogo filter (delogo)
Currently, six audio filters are supported. As is the case with the video filters above, many of them can be enabled/disabled in the config file.
- volume normalization (volnorm)
- the volume filter
- panning filter
- channels filter
- resample and lavcresample filter
At the moment, h264enc supports 9 different audio codecs: MP3, AC-3, E-AC-3, DTS, AAC (LC-AAC/HE-AACv1/HE-AACv2), Vorbis, Opus, FLAC and PCM. In addition, h264enc also supports the COPY and NOSOUND formats of MEncoder. For LC-AAC audio, h264enc supports three audio encoders; FAAC, FDK-AAC and neroAacEnc. For HE-AAC audio (also known as AAC+) one can either use neroAacEnc, FDK-AAC or the aacplusenc encoder. For Vorbis, Opus, AC-3, DTS and FLAC, the requirements are oggenc, opusenc, aften, dcaenc and flac, respectively. h264enc supports virtually an unlimited (yes, really!) amount of audio tracks. The amount of audio tracks the user wants can be set in a variable in the config file. Things that can be set per track at runtime include:
- Per track audio codec and settings
- Per track audio channels
- Per track audio volume normalization
- Per track audio volume adjustments
- Per track audio panning
- Per track audio resampling
If you intend to use the FDK-AAC encoder, you have to checkout the code from here and configure it with --enable-example in order to build the aac-enc executable! After that, you need to recreate the config file of h264enc using the -r option or manually set the path to aac-enc either by using the -e option or opening the config file with your favorite text editor and modifying the FDKAACENC variable.
- Audio Channels Downmixing
With the the release of Blu-ray and HD content, many videos released today come with audio that has more than 5.1 channels. h264enc supports a maximum of 5.1 channels audio due to most of the audio encoders supported by the script can only do no more than 5.1 channels. It could be problematic to encode such content with more than 5.1 channels directly in h264enc but there are a few options you have at hand.
- Use eac3to to downmix to 5.1 channels: eac3to is a very handy Windows tool that works with no issues under Wine and is very easy to use. I highly recommend it and use it myself to downmix from 6.1 or 7.1 channels down to 5.1. It can directly read from video files/Blu-rays stored on disk so you do not need to first extract the original audio and pass it through eac3to. My typical workflow with eac3to in a console is this: wine /path/to/eac3to.exe input.mkv output.wav -down6 -no2ndpass. This will downmix the audio to 5.1 channels in an output.wav file. Then I use a muxer (for example mkvmerge) to mux the unmodified original video and the downmixed audio into an mkv file which then I use as input for h264enc to encode and set the decode channels to 6 together with an audio codec (like AC-3 or AAC which support multi-channels) to compress the PCM audio during encoding.
- Encode with the NOSOUND option: you can encode the content with the nosound option which ignores the audio. After that, you can extract the audio from the original video and use a muxer like mkvmerge or MP4Box to mux both the encoded video and the original audio. This way you can preserve the amount of channels of the original.
- Use the COPY option in h264enc: the copy option does what it says. It copies the audio without modifications (so you won't be able to use audio filters). This option can be tricky and may or may not work correctly at times. It really depends on the codec you're trying to copy. I've seen some videos with DTS audio where you get a desync in the encoded file and I've also seen some where this is not a problem. YMMV.
Other things that are supported include...
- Support for EDL List files
- Multiple formulas for video bitrate calculation for a target file size.
- Calculation of maximum allowed frame references within DPB limits for different levels and resolutions.
- 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.
- Automatic calculation of Pixel Aspect Ratio (PAR) and total pixels from resolution.
- Ability to force the input aspect ratio.
- Colorspace conversion during scaling.
- Proper alignment of Chroma channels for interlacing preservation.
- 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 and directories.
- Supports scanning the input video file for multiple video streams.
- Sanity check which displays in a menu if the required programs are installed or missing.
- Email notifications when encoding finishes.
- 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 to encode multiple files from a given directory.
- Supports virtually an unlimited amount of audio tracks.
- Supports virtually an unlimited amount of subtitles.
- 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, though this is possible with custom presets.
- Does not require the graphical X Window system, if you do not use crop preview and sample encoding.
- The user can enable/disable specific audio/video filters and containers in the config file.
- 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 audio and 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.
- Cannot batch encode DVDs/Blu-rays/(S)VCDs yet.
- Supports a max of 5.1 audio channels so anything higher is not supported yet.
- Subtitles for the TS container are not supported yet due to the brokenness of tsMuxeR for Linux.
- Probably a few more I can't think of now.
