Ticket #1349: transcoding-doc.patch

docs/mythtv-HOWTO.sgml

@@ -6334 +6334 @@
 content even if the slave backend that recorded a program is not available.
 
 <sect1>What is this transcoder thing, and how do I use it?
-<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>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 MPEG4 streams to
+save space.  However, with the addition of HD sources transcoding has
+come to be used to transcode and resize HD MPEG2 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>
+<p>When MythTV transcodes a file to MPEG4 or RTjpeg the file format is
+actually NuppelVideo (nuv.)  You may have difficulty playing these
+files back in other video players.  If you want something more
+portable you can look at some of the other sections in this HOWTO.
 
-The transcoder can be used in two ways:
+<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 necessary
+to leave this option enabled.
+</p>
+
+<p>A recording can be transcoded in two ways:
 <itemize>
-<item>Automatically re-encode every file once it has completed recording
-<item> After marking commercials, the transcoder can be run manually to
-delete the commercials from the file (thus further saving space)
+<item>Automatically transcode the file once it has completed
+recording.</item>
+<item>Manually choosing to transcode a recording, usually after
+importing a cutlist or manually marking commercials to be
+removed.</item>
 </itemize>
-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.
 
-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>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>
 
-To enable automatic transcoding, do the following:
-   start the setup program
-   under the host-specific settings:
-      set the Transcoder Auto-run checkbox
+<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:
+<enum>
+<item>Configure recording profile for your capture source and enable
+transcoding on one or more profiles.</item>
+<item>Configure one or more transcoding profiles.</item>
+<item>Create or alter existing scheduled recordings to enable
+transcoding for that recording.</item>
+</enum>
 
-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)
+<sect2>Configuring Recording Profiles to Allow Transcoding
 
-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>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>
 
-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.
+<sect2>Configure Transcoding Profiles
 
-Once the transcode is complete, mythbackend will replace the old file
-with the new as soon as it is no longer in use.
+<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 MPEG2 recording.  If you choose one of the
+others (High, Medium, 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 <em>and</em> the recording will take <em>more</em> 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 experiment with until you achieve a good
+compromise between size and quality. 
+<p>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.
+
+<sect2>Create/Alter Scheduled Recordings to Enable Transcoding
+
+<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 MPEG2 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>
+
+<sect2>Manual Transcoding
+<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. 
+<p>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.  The transcoder column contains a number which
+corresponds with the id column in the recordingprofiles table.  You
+can find out the id number for each profile in the transcoder group
+with an SQL command like:
+
+<tscreen><verb>
+mysql> select r.* from recordingprofiles r,profilegroups p where p.name='Transcoders' and p.id=r.profilegroup;
++----+----------------+------------+------------+--------------+
+| id | name           | videocodec | audiocodec | profilegroup |
++----+----------------+------------+------------+--------------+
+| 21 | RTjpeg/MPEG4   | MPEG-4     | MP3        |            6 |
+| 22 | MPEG2          | MPEG-4     | MP3        |            6 |
+| 27 | High Quality   | MPEG-4     | MP3        |            6 |
+| 28 | Medium Quality | MPEG-4     | MP3        |            6 |
+| 29 | Low Quality    | MPEG-4     | MP3        |            6 |
++----+----------------+------------+------------+--------------+
+5 rows in set (0.01 sec)
+
+mysql>                                                                        
+</verb></tscreen>
+
+<p>Armed with the knowledge of what the profile ID's are you can also
+choose to run mythtranscode from the command line explicitly
+specifying the transcoder profile.  Run mythtranscode with --help for
+usage information.
+
+
 <sect1>Changing your hostname
 <!-- Edited instructions from a post by Alan Snyder ax763 at yahoo.com -->
 <p>If you need to change the name of the computers used with MythTV you'll