transcode(1)

NAME
transcode - LINUX video stream processing tool

SYNOPSIS
transcode [ options ] ...

COPYRIGHT
transcode is Copyright (C) by Thomas Östreich.

DESCRIPTION

transcode is a linux text-console utility for video stream processing, running on a platform that supports shared libraries and threads.

Decoding and encoding is done by loading modules that are responsible for feeding transcode with raw video/audio streams (import modules) and encoding the frames (export modules).

It supports elementary video and audio frame transformations, including de-interlacing or fast resizing of video frames and loading of external filters.

A number of modules are included to enable import of DVDs on-the-fly, MPEG elementary (ES) or program streams (VOB), MPEG video, Digital Video (DV), YUV4MPEG streams, NuppelVideo file format and raw or compressed (pass-through) video frames and export modules for writing DivX;-), XviD, DivX 4.xx/5.xx or uncompressed AVI files with MPEG, AC3 (pass-through) or PCM audio.

Additional export modules to write single frames (PPM) or YUV4MPEG streams are available, as well as an interface import module to the avifile library.

It's modular concept is intended to provide flexibility and easy user extensibility to include other video/audio codecs or filetypes. A set of tools is included to demux (tcdemux), extract (tcextract) and decode (tcdecode) the sources into raw video/audio streams for import, probing (tcprobe) and scanning (tcscan) your sources and to enable post-processing of AVI files, fixing AVI file header information (avifix), merging multiple files (avimerge) or splitting large AVI files (avisplit) to fit on a CD.

OPTIONS

-A  use AC3 as internal audio codec [off].
    Only pass-through supported.

-B n[,m[,M]]
    resize to height-n*M rows [,width-m*M] columns [off,32]. M must be one of 8, 16 or 32.

-C mode
    enable anti-aliasing mode (1-3) [off].
    1 "de-interlace effects only" 2 "resize effects only" 3 "process full frame (slow)"

-D num
    sync video start with audio frame num [0].

-E r[,b[,c]]
    audio output samplerate [Hz], bits per sample and channels [as input]. The option "-J resample" must be provided for export modules not capable of re-sampling.

-F codec
    encoder parameter strings [module dependent].

-G val
    gamma correction (0.0-10.0) [off].

-H n
    auto-probe n MB of source (0=disable) default [1]

-I mode
    enable de-interlacing mode (1-5) [off].
    1 "interpolate scanlines"
        linear interpolation (takes the average of the
        surronding even rows to determine the odd rows),
        and copies the even rows as is. 2 "handled by encoder"
        tells the encoding code to handle the fact that the
        frames are interlaced. Most codecs do not handle this. 3 "zoom to full frame"
        drops to to half size, then zooms out. This can cause
        excessive blurring which is not always unwanted. On
        the other hand results are quite good. 4 "drop field / half height"
        drop every other field and keep half height. 5 "interpolate scanlines / blend frames"
        linear blend (similar to -vop pp=lb in mplayer) this,
        like linear blend calculates the odd rows as the
        average of the surronding even rows, and also
        calculates the even rows as an average of the
        original even rows and also calculates the even rows
        as an average of the original odd rows and averages
        the calculated and original rows.

-J filter1[,filter2[,...]]
    apply external filter plugins [off]. A full-blown transcode installation has the following filter modules:

    Filter "29to23": 29.97 to 23.976 frame rate conversion
    Filter "32detect": 3:2 pulldown detection plugin
    Filter "32drop": 3:2 inverse telecine removal plugin
    Filter "aclip": generate audio clips from source, cuts out silence
    Filter "astat": audio statistics filter plugin
    Filter "cshift": chroma-lag shifter
    Filter "cut": encode only listed frames
    Filter "decimate": NTSC decimation plugin
    Filter "divxkey": detect keyframes in MPEG-4 bitstreams
    Filter "dilyuvmmx": yuv de-interlace filter plugin
    Filter "dnr": dynamic noise reduction
    Filter "extsub": subtitle renderer
    Filter "extsub2": secondary subtitle renderer
    Filter "invert": invert the image
    Filter "ivtc": NTSC inverse telecine plugin
    Filter "logo": render image in videostream
    Filter "mask": masking plugin
    Filter "normalize": Volume normalizer
    Filter "null": API demo filter plugin
    Filter "pp": mplayer postprocess filters
    Filter "preview": preview filter
    Filter "pv": xv only preview filter with navigation keys
    Filter "resample": audio resample filter
    Filter "skip": skip all listed frames
    Filter "smartdeinter": VirtualDub's smart deinterlacer
    Filter "smooth": single-frame smoothing plugin
    Filter "subtitler": powerful custom subtitle generator
    Filter "tc_audio": audio 24000/1001 -> 30000/1001 telecide filter
    Filter "tc_video": video 24000/1001 -> 30000/1001 telecide filter
    Filter "testframe": generate stream of testframes
    Filter "xsharpen": VirtualDub's XSharpen Filter
    Filter "yuvdenoise": mjpegs YUV denoiser
    Filter "yuvmedian": mjpegs median filter

    To see what your transcode has, do a
    ls -1 `tcmodinfo -p`/filter*.so

Example:
    transcode [...] -J 32detect=force_mode=3,normalize,cut="0-100 300-400" Will load the 32detect filter plugin with parameter force_mode=3, the volume normalizer and the cut filter. Some of the filter plugins have additional documentation in /docs/filter_*.txt

Note:
    You can specify more than one -J argument. The order of filter arguments specify in which order the filters are applied. Note also, for transcode internally it makes no difference whether you do "-J filter1 -J filter2" or "-J filter1,filter2"

-L n
    seek to VOB stream offset nx2kB default [0]

-K enable b/w mode [off].

-M mode
    demuxer PES AV sync modes (0-4) [1].

    0 pass-through, do not mess with the stream, switch off
           any synchronization/demuxing process. 1 PTS only (default)
           Synchronize video and audio by inspecting PTS/DTS
           time stamps of audio and video. Preferred mode for
           PAL VOB streams and DVDs. 2 NTSC VOB stream synchronization
           feature. This mode generates synchronization
           information for transcode by analyzing the frame
           display time. 3 (like -M 1) but invokes "-D/--av_fine_ms" options
           internally based on "tcprobe" PTS analysis. 4 (like -M 2) with additional frame rate enforcement
           (for NTSC).

-N 0xnn
    export audio format id [0x55].
    Available format IDs are: 0x1 PCM uncompressed audio 0x50 MPEG layer-2 aka MP2 (only with -y *,mpeg) 0x55 MPEG layer-3 aka MP3 0x2000 AC3 audio (only with -A) 0xfffe OGG/Vorbis audio

-O  flush lame mp3 buffer on encoder stop [off].

-P flag
    pass-through flag (0=off|1=V|2=A|3=A+V) [0].

-Q n[,m]
    encoding[,decoding] quality (0=fastest-5=best) [5,5].

-R n[,f1[,f2]]
    enable multi-pass encoding (0-3) [0,divx4.log,pcm.log].

-S unit[,s1-s2]
    process program stream unit[,s1-s2] sequences [0,all].

-T t[,c[,a]]
    select DVD title[,chapter[,angle]] [1,1,1]. Only a single chapter is transcoded. Use -T 1,-1 to trancode all chapters in a row. You can even specify chapter ranges.

-U base
    process DVD in chapter mode to base-ch%02d.avi [off].

-V  use YV12/I420 as internal video codec [off]. This is usually much faster than RGB processing but some import modules may not support this format. Always use this option when possible

-W n,m[,nav_file]
    autosplit and process part n of m (VOB only) [off]

-X n[,m,[M]]
    resize to height+n*M rows [,width+m*M] columns [off,32]. M must be one of 8, 16 or 32.

-Y top[,left[,bottom[,right]]]
    select (encoder) frame region by clipping border. Negative values add a border [off].

-Z widthxheight
    resize to widht columns, height rows with filtering [off].

-a ach[,vch]
    extract audio[,video] track for encoding.

-b b[,vbr,[q]]
    audio encoder bitrate kBits/s[,vbr[,quality]] [128,0,5]

-c f1-f2[,f3-f4[, ... ] ]
    encode only frames f1-f2 [and f3-f4]. Default is to encode all available frames. Use this and you'll get statistics about remaining encoding time. The f[N] parameters may also be timecodes in the HH:MM:SS.FRAME format.
    Example: -c 500-0:5:01,:10:20-1:18:02.1

    Will encode only from frame 500 to 5 minutes and 1 second and from 10 min, 20 sec to 1 hour, 18 min, 2 sec and one frame.

-d  swap bytes in audio stream [off]. In most cases, DVD PCM audio tracks require swapping of audio bytes

-e r[,b[,c]]
    PCM audio stream parameter. Sample rate [Hz], bits per sample and number of channels [48000,16,2].

-f rate[,frc]
    output video frame rate[,frc] [25.000,0]. If frc (frame rate code) is specified, transcode will calculate the precise frames per second internally. Valid values for frc are

      1 : 23.976 (24000/1001.0)
      2 : 24
      3 : 25
      4 : 29.970 (30000/1001.0)
      5 : 30
      6 : 50
      7 : 59.940 (2 * 29.970)
      8 : 60
      9 : 1
     10 : 5
     11 : 10
     12 : 12
     13 : 15

-g widthxheight
    video stream frame size [720x576].

-h  print out usage information.

-i name
    input file/directory/device/mountpoint/host name, default is [/dev/zero].

-j top[,left[,bottom[,right]]]
    select frame region by clipping border. Negative values add a border [off].

-k  swap red/blue (Cb/Cr) in video frame [off]. Use if people have blue faces.

-l  mirror video frame [off].

-m file
    write audio stream to separate file [off].

-n 0xnn
    import audio format id [0x2000]. Normally, this is autodetected.

-o file
    output file name, default is [/dev/null].

-p file
    read audio stream from separate file [off].

-q level
    verbosity (0=quiet,1=info,2=debug) [1].

-r n[,m]
    reduce video height/width by n[,m] [off].

-s gain,[center,[front,[rear]]]
    increase volume of audio stream by gain[center,front,rear] default [off,1,1,1].

-t n,base
    split output to base%03d.avi with n frames [off].

-u m[,n]
    use m framebuffer[,n threads] for AV processing [10,1].

-v  print version.

-w b[,k[,c]]
    encoder bitrate[,keyframes[,crispness]] [1800,250,100].

-x vmod[,amod]
    video[,audio] import modules [auto,auto]. If omitted, transcode will probe for appropriate import modules. A full-blown transcode installation has the following import modules:

    Module "ac3": (audio) AC3
    Module "af6": (video) Win32 dll | (audio) PCM
    Module "avi": (video) * | (audio) *
    Module "divx": (video) DivX;-)/XviD/OpenDivX/DivX 4.xx/5.xx
    Module "dv": (video) DV | (audio) PCM
    Module "dvd": (video) DVD | (audio) MPEG/AC3/PCM
    Module "ffmpeg": (video) FFMPEG API (build 4631) | MS MPEG4v1-3/MPEG4/MJPEG
    Module "im": (video) RGB
    Module "imlist": (video) RGB
    Module "lav": (video) LAV | (audio) WAVE
    Module "lzo": (video)
    Module "mjpeg": (video) MJPEG
    Module "mov": (video) * | (audio) *
    Module "mp3": (audio) MPEG
    Module "mpeg2": (video) MPEG2
    Module "mpeg3": (video) MPEG2
    Module "mplayer": (video) rendered by mplayer | (audio) rendered by mplayer
    Module "null": (video) null | (audio) null
    Module "nvrec": (video) nvrec - v4l | (audio) nvrec - dsp
    Module "ogg": (audio) OGG Vorbis
    Module "raw": (video) RGB/YUV | (audio) PCM
    Module "rawlist": (video) YUV/RGB raw frames
    Module "vdrac3": (audio) VDR-AC3
    Module "vob": (video) MPEG-2 | (audio) MPEG/AC3/PCM | (subtitle)
    Module "v4l": (video) YUV/RGB | (audio) PCM
    Module "xml": (video) * | (audio) *
    Module "xvid": (video) XviD/OpenDivX/DivX 4.xx/5.xx
    Module "yuv4mpeg": (video) YUV4MPEGx | (audio) WAVE

    To see what your transcode has, do a
    ls -1 $TRANSCODE_MOD_PATH/import*.so

    It is possible to pass option strings to import modules like to filter modules. The average user does not this feature and not many modules support it. The syntax is -x vmod=options,amod=options
    Example
      -x rawlist=uyvy,null
    To tell the rawlist import module (which reads images from a list of files) the colour space of the images.

-y vmod[,amod]
    video[,audio] export modules [null]. If omitted, transcode will encode to the null module. A full-blown transcode installation has the following export modules:

    Module "af6": (video) Win32 dll | (audio) MPEG/AC3/PCM
    Module "divx4": (video) DivX 4.xx | (audio) MPEG/AC3/PCM
    Module "divx4raw": (video) DivX 4.xx (ES) | (audio) MPEG/AC3/PCM
    Module "divx5": (video) DivX 5.xx | (audio) MPEG/AC3/PCM
    Module "divx5raw": (video) DivX 5.xx (ES) | (audio) MPEG/AC3/PCM
    Module "dv": (video) Digital Video | (audio) MPEG/AC3/PCM
    Module "dvraw": (video) Digital Video | (audio) PCM
    Module "fame": (video) MPEG-4 | (audio) MPEG/AC3/PCM
    Module "ffmpeg": (video) ffmpeg API | (audio) MPEG/AC3/PCM
    Module "im": (video) *
    Module "jpg": (video) *
    Module "lame": (audio) MPEG 1/2
    Module "lzo": (video) LZO | (audio) MPEG/AC3/PCM
    Module "mjpeg": (video) Motion JPEG | (audio) MPEG/AC3/PCM
    Module "mov": (video) * | (audio) *
    Module "mp2enc": (audio) MPEG 1/2
    Module "mpeg2enc": (video) MPEG 1/2
    Module "mpeg": (video) MPEG 1/2 | (audio) MPEG 1 Layer II
    Module "net": (video) RGB/YUV | (audio) PCM/AC3
    Module "null": (video) null | (audio) null
    Module "ogg": (video) null | (audio) OGG Vorbis
    Module "pcm": (audio) PCM (non-interleaved)
    Module "ppm": (video) PPM/PGM | (audio) MPEG/AC3/PCM
    Module "raw": (video) * | (audio) MPEG/AC3/PCM
    Module "sampeg": (video) MPEG-2
    Module "toolame": (audio) MPEG 1/2
    Module "wav": (audio) WAVE PCM
    Module "xvid": (video) XviD API 1.0 and 2.0 | (audio) MPEG/AC3/PCM
    Module "xvidcvs": (video) Xvid API 1.0 and 2.0 (CVS) | (audio) MPEG/AC3/PCM
    Module "xvidraw": (video) Xvid API 1.0 and 2.0 (CVS) | (audio) MPEG/AC3/PCM
    Module "yuv4mpeg": (video) YUV4MPEG2 | (audio) MPEG/AC3/PCM

    To see what your transcode has, do a
    ls -1 $TRANSCODE_MOD_PATH/export*.so

    It is possible to pass option strings to export modules like to filter modules. The syntax is -y vmod=options,amod=options

-z  flip video frame upside down [off].

--accel type
    enforce experimental IA32 acceleration for type [autodetect].

--avi_limit N
    split output AVI file after N MB [2048].

--zoom_filter string
    use filter string for video resampling -Z [Lanczos3]

--cluster_percentage
    use percentage mode for cluster encoding -W [off]

--cluster_chunks a-b
    process chunk range instead of selected chunk [off]

--export_asr C
    set export aspect ratio code C [as input]

    Valid codes for C are:
         1 1:1
         2 4:3
         3 16:9
         4 2.21:1

--import_asr C
    set import aspect ratio code C [autoprobed]

    Valid codes for C are:
         1 1:1
         2 4:3
         3 16:9
         4 2.21:1

--keep_asr
    try to keep aspect ratio (only with -Z) [off]

    The --keep_asr options changes the meaning of -Z. It tries to fit the video into a framesize specified by -Z by keeping the original aspect ratio. /----------------\ /---480-----\
    | | | black |
    |720x306 = 2.35:1| -> -Z 480x480 --keep_asr ->|-----------4
    | | | 480x204 8
    \----------------/ |-----------0
                            | black |
                            \-----------/
    Consider --keep_asr a wrapper for calculating -Y options and -Z options

--divx_quant min,max
    divx encoder min/max quantizer [2,31]

--divx_rc p,rp,rr
    divx encoder rate control parameter [2000,10,20]

--export_frc F
    set export frame rate code F [as input]

--import_v4l n[,id]
    channel number and station number or name [0]

--record_v4l a-b
    recording time interval in seconds [off]

--duration hh:mm:ss
    limit v4l recording to this duration [off]

--pulldown
    set MPEG 3:2 pulldown flags on export [off]

--antialias_para w,b
    center pixel weight, xy-bias [0.333,0.500]

--no_audio_adjust
    disable internal audio frame sample adjustment [off]

--no_bitreservoir
    disable lame bitreservoir for MP3 encoding [off]

--av_fine_ms t
    AV fine-tuning shift t in millisecs [autodetect]

--nav_seek file
    use VOB navigation file [off] Generate a nav file with tcdemux -W >nav_log

--psu_mode
    process VOB in PSU, -o is a filemask incl. %d [off]. PSU means Program Stream Unit and this mode is useful for (mostly) NTSC DVDs which have several program stream units.

--psu_chunks a-b
    process only selected units a-b for PSU mode [all]

--no_split
    encode to single file in chapter/psu/directory mode [off]

--pre_clip t[,l[,b[,r]]]
    select initial frame region by clipping border [off]

--post_clip t[,l[,b[,r]]]
    select final frame region by clipping border [off]

--a52_drc_off
    disable liba52 dynamic range compression [enabled]

--a52_demux
    demux AC3/A52 to separate channels [off]

--a52_dolby_off
    disable liba52 dolby surround [enabled]

--dir_mode base
    process directory contents to base-%03d.avi [off]

--frame_interval N
    select only every Nth frame to be exported [1]

--encode_fields
    enable field based encoding (if supported) [off]

--write_pid file
    write pid of signal thread to file [off] Enables you to terminate transcode cleanly by sending a SIGINT (2) to the pid in file. Please note file will be overwritten. Usage example

    $ transcode ... --write_pid /tmp/transcode.pid &
    $ kill -2 `cat /tmp/transcode.pid`

--print_status N[,usecr]
    print status every N frames / use CR or NL [1,1]
    The first parameter controls how frequently the status message is printed (every N frames), the second parameter (if provided) controls whether transcode ends the line with a CR ('\r') or NL ('\n') character. Transcode defaults to ending with a CR if its output is going to a terminal, or a LF if its output is going to somewhere else (such as a logfile), so most people shouldn't have any need to specify the second parameter since it should do the right thing most of the time.

--write_pid file
    write pid of signal thread to file [off] Enables you to terminate transcode cleanly by sending a SIGINT (2) to the pid in file. Please note file will be overwritten. Usage example

    $ transcode ... --write_pid /tmp/transcode.pid &
    $ kill -2 `cat /tmp/transcode.pid`

--socket FILE
    Open a socket to accept commands while running. See tcmodinfo(1) and /docs/filter-socket.txt for more information about the protocol.

--more_help param
    more help on named parameter (if supported)

NOTES

*   Most source material parameter are auto-detected.

*   Clipping region options are expanded symmetrically. Examples:

    -j 80 will be expanded to -j 80,0,80,0

    -j 80,8 will be expanded to -j 80,8,80,8

    -j 80,8,10 will be expanded to -j 80,8,10,8

*   maximum image size is 1024x768.

*   The video frame operations ordering is fixed: "-j -I -X -B -Z -Y -r -z -l -k -K -G -C" (executed from left to right).

*   Shrinking the image with '-B' is not possible if the image width/height is not a multiple of 8, 16 or 32.

*   Expanding the image with '-X' is not possible if the image width/height is not a multiple of 8, 16 or 32.

*   The final frame width/height should be a multiple of 8. (to avoid encoding problems with some codecs)

    1.  Reducing the video height/width by 2,4,8 Option '-r factor' can be used to shrink the video image by a constant factor, this factor can be 2,4 or 8.

    2.  Clipping and changing the aspect ratio transcode uses 3 steps to produce the input image for the export modules

        1.  Clipping of the input image.

        2.  Changing the aspect ratio of the 1) output.

        3.  Clipping of the 2) output.

*   Bits per pixel (bits/pixel) is a value transcode calculates and prints when starting up. It is mainly useful when encoding to divx. You'll see line like
    [transcode] V: bits/pixel | 0.237 Simplified said, bits/pixel quantifies how good an encode will be. Although this value depends heavily on the used input material, as a general rule of thump it can be said that values greater or close to 0.2 will result in good encodes, encodes with values less than 0.15 will have noticeable artifacts. Bits per pixel depends on the resolution, bitrate and frames per second. If you have a low value ( < 0.15), you might want to raise the bitrate or encode at a lower resolution. The exact formula is
               bitrate*1000
      bpp = ----------------
             width*height*fps

*   AC3 / Multiple channels When you do import an audio stream which has more then two audio channels - this is usually the case for AC3 audio - transcode will automagically downmix to two channels (stereo). You'll see line like
    [transcode] A: downmix | 5 channels -> 2 channels This is done, because most encoders and audio filters can not handle more than 2 channels correctly. The PCM internal representation does not support more than two channels, audio will be downmixed to stereo No downmix will happen, if you use AC3 as the internal audio codec or use audio pass-through.

EXAMPLES
The following command will read it's input from the DVD drive (I assume /dev/dvd is a symbolic link to the actual DVD device) and produce a splitted divx4 movie according to the chapter information on the DVD medium. The output files will be named my_movie-ch00.avi, my_movie-ch01.avi ...

transcode -i /dev/dvd/ -x dvd -V -j 16,0 -B 5,0 \
    -Y 40,8 -s 4.47 -U my_movie -y divx4 -w 1618

Option -V tells transcode to use YUV as internal video colorspace, which saves a lot of CPU/PCI bandwidth.

Option -j 16,0 will be expanded to -j 16,0,16,0 and results in 16 rows from the top and the bottom of the image to be cut off. This may be usefull if the source consists of black top and bottom bars.

Option -B 5,0 tells transcode to shrink the resulting image by 5*32=160 rows in height.

Option -Y 40,8 will be expanded to -Y 40,8,40,8 and tells transcode to ...

Option -s 4.47 tells transcode to increase audio volume by a factor 4.47.

Option -U my_movie tells transcode to operate in chapter mode and produce output to files named my_movie-ch00.avi, my_movie-ch01.avi...

Option -y divx4 tells transcode to use the export module export_divx4.so.

Option -w 1618 tells transcode to set the encoder bitrate to 1618 which is lower than the default of 1800 and results in smaller files with the loss of visual quality.

AUTHORS
transcode was written by Thomas Östreich
<ostreich@theorie.physik.uni-goettingen.de> with contributions from many others. See AUTHORS for details.

SEE ALSO
avifix(1), avisync(1), avimerge(1), avisplit(1), tcprobe(1), tcscan(1), tccat(1), tcdemux(1), tcextract(1), tcdecode(1), tcmodinfo(1), transcode(1)

WWW
Frequently asked questions (FAQ) at
http://www.theorie.physik.uni-goettingen.de/~ostreich/transcode/html/faq.html
Example transcode sessions
http://www.theorie.physik.uni-goettingen.de/~ostreich/transcode/html/index.html

BUGS
see http://www.theorie.physik.uni-goettingen.de/~ostreich/transcode/pending.html