[mythtv] updating the HOWTO regarding transcoding (patch included)

[Aran Cox]

It appears the documentation for transcoding in the HOWTO (23.14)
hasn't been updated since the changes made in May of last year. So, I
thought I'd try my hand at updating them.  It's maybe too wordy, but
transcoding configuration is very flexible now and I was trying to be
very clear.  I will attach the HTML so you can just peruse it and a
patch (technically against mythtv-release-0-19-fixes, but should be
applied to trunk as well.)

Hopefully someone will have the time to read it over and make sure I
haven't gotten anything too terrible wrong.  I assume if it's OK, it
could be folded into the User manual on the wiki as well.

Aran
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mythtv.org/pipermail/mythtv-dev/attachments/20060217/e7371ca9/attachment.html 
-------------- next part --------------
Index: docs/mythtv-HOWTO-23.html
===================================================================
--- docs/mythtv-HOWTO-23.html	(revision 9020)
+++ docs/mythtv-HOWTO-23.html	(working copy)
@@ -674,51 +674,152 @@
 <H2><A NAME="ss23.14">23.14</A> <A HREF="mythtv-HOWTO.html#toc23.14">What is this transcoder thing, and how do I use it?</A>
 </H2>
 
-<P>The transcoder re-encodes files from one MythTV format to another.  The
-main purpose of the transcoder is to allow users with hardware
-encoders (PVR-250) or systems that can only record in RTjpeg due to
-performance reasons (multiple capture cards, slow system, etc) to create
-MPEG-4 streams to save space.</P>
-<P>The transcoder can be used in two ways:
+<P>MythTV's built-in transcoder re-encodes recordings from one
+codec/format to another.  Transcoding is most commonly used to allow
+users with hardware encoders (PVR cards, DVB cards, ATSC HD, etc.) or
+systems that can only record in RTjpeg due to performance reasons
+(multiple capture cards, slow system, etc) to create MPEG-4 streams to
+save space.  However, with the addition of HD sources transcoding has
+come to be used to transcode and resize HD MPEG-2 recordings into
+MPEG4 files to be played on systems too slow to deal with the original
+HD recordings.  There are even more uses for transcoding though,
+including the ability to fix up MPEG2 recordings or remove commercials
+without transcoding at all.
+<P> The original file is actually removed when the transcoding process
+is complete.  Unless you're sure that you will be satisfied with the
+result you may want to enable the mythv-setup option which causes
+mythbackend to keep the original after transcoding.  This option is on
+the second page of the General section in mythtv-setup.  Enabling this
+allows you to compare the two files and restore the original if you
+like.  Outside of the initial setup phase, it usually isn't neccesary
+to leave this option enabled.
+</P>
+
+<P>A recording can be transcoded in two ways:
 <UL>
-<LI>Automatically re-encode every file once it has completed recording</LI>
-<LI> After marking commercials, the transcoder can be run manually to
-delete the commercials from the file (thus further saving space)</LI>
+<LI>Automatically transcode the file once it has completed
+recording.</LI>
+<LI>Manually choosing to transcode a recording, usually after
+importing a cutlist or manually marking commercials to be
+removed.</LI>
 </UL>
 
-The two methods are independent.  The first is an automatic process that can be
-enabled/disabled through the setup program; the second is a manual method which
-must be invoked on each recording individually.</P>
-<P>The second method can be used on files that have already been transcoded (or
-files which were are already in the correct format), so only the frames
-immediately following a cut section will be re-encoded, resulting in a very
-minimal loss of quality.</P>
-<P>To enable automatic transcoding, do the following:
-start the setup program
-under the host-specific settings:
-set the Transcoder Auto-run checkbox</P>
-<P>For either manual or automatic transcoding:
-start mythbackend
-start mythfrontend
-select setup, and the Transcoding recording profile.
-now select either RTjpeg or MPEG-4 (selecting any of the hardware
-encoders will result in the transcoder not working).
-set the other parameters as you'd like.  For best performance, you
-should match the audio to the 'Default' profile.  If you plan to
-only use the manual transcoder, you can choose to set the video to
-be the same as the default profile too (as long as it is MPEG-4 or
-RTjpeg)</P>
-<P>Everything should now be setup properly.  If you elected to use the
-Auto-Run feature, the transcoder will automatically launch after each
-recording is complete.  The transcoder thread runs at a low priority, so it
-should not impact any critical tasks or other recordings.</P>
-<P>If you want to manually transcode a program, simply press 'X' while
-watching a recording (you should have already finished marking all
-commercials).  If you change your mind, hitting 'X' again will stop the
-transcoding.</P>
-<P>Once the transcode is complete, mythbackend will replace the old file
-with the new as soon as it is no longer in use.</P>
+<P>The second method can be used on files that have already been
+transcoded (or files which were are already in the desired format), so
+only the frames immediately following a cut section will be
+re-encoded, resulting in a very minimal loss of quality when removing
+commercials.</P>
 
+<P>The current transcoding system has a lot flexibility, but there are
+a number of steps involved in setting it up.  In order to
+automatically transcode a given recording you must do the following:</P>
+<OL>
+<LI>Configure recording profile for your capture source and enable
+transcoding on one or more profiles.</LI>
+<LI>Configure one or more transcoding profiles.</LI>
+<LI>Create or alter existing scheduled recordings to enable
+transcoding for that recording.</LI>
+</OL>
+
+<H3>Configuring Recording Profiles to Allow Transcoding</H3>
+
+<P>Enter the Utilities/Setup,Setup,TV Settings,Recording Profiles
+section in mythfrontend.  Choose the option that corresponds with your
+capture source (ignore the Transcoders for now.)  Choose the quality
+profile you are interested in enabling auto-transcode for.  Make sure
+"Enable auto-transcode after recording" is checked.  This option might
+ought to be called "allow auto-transcode" as we'll soon see though.
+You might want to verify that the other settings for this profile are
+correct while your here.</P>
+
+<H3>Configure Transcoding Profiles</H3>
+
+<P>Enter the Transcoders section under Recording Profiles.  There are
+three quality settings to choose from and a two special Autodetect
+settings.  Later, when scheduling recordings you'll have to choose one
+of Autodetect, High, Medium, and Low Quality transcode settings in
+addition to the recording profile we set up above.  If you choose the
+Autodetect transcoding profile for a recording, MythTV will use the
+"Autodetect from RTjpeg/MPEG4" profile for recordings which are
+RTjpeg/MPEG4 files.  Otherwise, it will use the "Autodetect from
+MPEG2" provided it's an MPEG-2 recording.  If you choose one of the
+others (High, Med. Low) it will use the settings in that profile
+regardless of the codec of the original recording.</P>
+
+<P>There are a myriad of options for transcoding but the simplest
+setting is to enable lossless transcoding (the first option) as this
+removes all other options. Enabling lossless encoding simply removes
+commercials (if you've marked them) and attempts to clean up MPEG2
+streams.  Note: with this option MythTV will not apply denoise filters
+or anything of the sort.  It only attempts to massage the stream into
+something cleaner and less likely to have trouble with other less
+forgiving MPEG2 hardware/software (including players, video editors,
+etc.)</P>
+
+<P>If you enable resizing of the recording the next page has the
+settings for choosing the final resolution.  Note: MythTV will scale
+the video as appropriate not crop it to this resolution.</P>
+
+<P>The final two pages allow configuration of the video and audio
+codecs.  Although RTjpeg is an option for video codec I can think of
+no reason you'd want to transcode to that format.  It produces larger
+files than MPEG4 <i>and</i> the recording will take <i>more</i> CPU
+power to play back.  The MPEG4 settings are not exactly
+self-explanatory but you can judge for yourself the effects on the
+final file and it's easy to expirement with until you achieve a good
+compromise between size and quality. For those who've messed up their
+MPEG4 transcoding profile, the defaults from memory are Bitrate:
+2200-2500, MaxQ: 2, MinQ: 15, MaxQDiff: 3, and "Scale bitrate for
+frame size" is enabled.  The other options are unchecked.  If you're
+getting weird results from MPEG4 transcoding try setting as above and
+go from there.</P>
+
+<H3>Create/Alter Scheduled Recordings to Enable Transcoding</H3>
+
+<P>Transcoding is actually enabled on a per-recording basis.  Two
+things must be true before any given recording will be
+auto-transcoded, however.  The first is that the recording must have
+been made with a recording profile that has auto-transcode enabled.
+Under "Storage Options" for the recording you must set the "Record
+using the "X" profile" to the profile you configured in the first
+step.  In addition, under the "Post Recording Options" section of the
+recording you must also set "Transcode new recordings." This is also
+where you specify the Transcoding profile to use (Auto, High, Medium,
+Low.)</P>
+
+<P>It may not be obvious from above but the flexibility of this system
+is primarily to make it possible to auto-transcode a show recorded via
+one source (ie: pcHDTV 3000), and not transcode that same show if it's
+recorded on another kind of card (ie: PVR-250.)  There are other uses
+however.  You could have a PVR-250 and a V4L card.  You may want to
+transcode the MPEG2 from the PVR-250 but there is no need to transcode
+the recordings made with the V4L card, as it's already likely to be
+MPEG4.</P>
+
+<P>As an example, you could configure the Default profile for
+"Hardware DVB Encoders" (the profile group used for DVB cards,
+including the ATSC HD type cards like pcHDTV 3000) to "Enable
+auto-transcoding."  In the Default profile for MPEG-2 Encoders (PVR
+cards) you'd leave "Enable auto-transcoding" unchecked.  For programs
+that are available on both kinds of cards (think Law & Order, which is
+available on virtually every channel) you'd set the recording profile
+to Default and enable auto-transcoding in the record settings.  Then
+you pick your transcoding profile.  When Law & Order plays on your DVB
+card, it will get transcoded.  When it plays on a channel available
+via your PVR card, it won't be.</P>
+
+<P>Manually transcoding a recording is also possible.  It can be
+activated while watching a show by hitting 'x', or from the OSD menus
+by choosing the Transcode option, or by choosing Job Options/Transcode
+from the info menu accessed from the Watch or Delete Recordings
+screens.  The transcoding profile used for manual transcoding is
+whatever you set when you originally configured this recording, even
+if you didn't enable auto-transcoding.  The only way to change what
+transcoding profile will be used is to alter the transcoder column in
+the recorded table in the database.  This makes it difficult to decide
+after the fact whether or not to simply remove commercials or
+transcode to MPEG4.</P>
+     
 <H2><A NAME="ss23.15">23.15</A> <A HREF="mythtv-HOWTO.html#toc23.15">Changing your hostname</A>
 </H2>