dmconvert(1) dmconvert(1) NAME dmconvert - digital media file conversion utility SYNOPSIS dmconvert [options] infile1 [... infileN] [outfile] DESCRIPTION dmconvert converts between different digital media files. Input files are combined, converted, and written to an output file of a selected format. dmconvert may also be used to describe input files without converting to an output file. Supported files include the following audio, image, and movie formats. The output file format is specified with the -f option, and may be any of the formats except those marked describe-only or read-only. Format Description Audio aifc Audio Interchange File Format w/ compression aiff Audio Interchange File Format avr Audio Visual Research bicsf Berkeley/IRCAM/CARL Sound File Format iff Amiga IFF/8SVX d midi Musical Instrument Digital Interface mpeg1a MPEG-1 audio bitstream next NeXT/Sun audio rawaudio Raw audio data sd2 Sound Designer II sf2 Creative Labs SoundFont2 Compatible smp SampleVision voc Creative Labs VOC wave WAVE audio Image bmp Microsoft Windows Bit Map cur Microsoft Windows Cursor w eps Encapsulated PostScript fit File Format for Image Tiling gif Graphics Image File hdf Hierarchical Data Format ico Microsoft Windows Icon icon Sun Icon and Cursor jfif JPEG File Interchange Format mpnt Apple Macintosh MacPaint pbm Portable Bit Map r pcd Kodak PhotoCD pgm Portable Grayscale Map pic PIXAR Picture pict Apple Macintosh QuickDraw/PICT pix Alias Pixel pnm Portable Any Map ppm Portable Pixel Map w ps PostScript ras Sun Raster w rawrgb Raw pixels packed as rgb rgb SGI RGB image rgbA SGI RGB image with generated alpha rgba SGI RGB image with alpha rla Wavefront Raster rle Utah Runlength-encoded rpbm Raw Portable Bit Map rpgm Raw Portable Grayscale Map rpnm Raw Portable Any Map rppm Raw Portable Pixel Map r soft SoftImage PIC synu SDSC Synu tga Truevision Targa tiff Tagged Image File Format viff Khoros Visualization Image File Format x Stardent AVS X xbm X11 Bit Map xwd X Window Dump Movie avi AVI movie mpeg1s MPEG-1 systems bitstream mpeg1v MPEG-1 video bitstream qt QuickTime sgimv SGI movie r difdv DIF/DV bitstream (d = describe-only, r = read-only, w = write-only) At most one audio track and one video track is converted for each file. Input QuickTime files with multiple tracks are rendered as a single combined audio track and a single combined video track. The audio track in the output is obtained by concatenating audio tracks from the inputs, and likewise for the video track. Tracks to be written out may be selected and converted with the -p option. Sequences of image files may be specified in place of regular filename arguments by using special template strings. These template names contain a '#' character, and are defined using the -n option. If dmconvert is stopped with SIGINT (<Ctrl C>), a valid output file is written with whatever data has been processed. The signal SIGTERM also stops the program, but causes the output to be deleted. CONTENTS The next six sections discuss the many features that are supported. At the end of each section, several examples are provided to illustrate program usage. Options File Suboptions Audio Suboptions Video Suboptions Template Suboptions Conversions with Cosmo Movies OPTIONS -h Display help. No output file is generated. -D Describe the contents of the files. No output file is generated. -d Describe files as they are converted. -s Use short format for describing files. -l Use long format for describing files. Currently, this provides additional information only for some audio files. -q Quiet errors. Do not print error messages. -v Verbose progress. Print percentage completed during conversion. -f file_format[,suboptions] Output file specification. File_format may be any of the digital media formats except those that are read-only. Some file characteristics may be set with the suboptions described in the File Suboptions section. -p path[,suboptions] Enable the specified path to the output file. Path is a track type and may be "audio" or "video". Data conversion operations on enabled paths may be characterized by using the suboptions described in the Audio and Video Suboptions sections. If this option is not used, all tracks are enabled by default. If this option is used, each track to be written out must be explicitly enabled. -n template_name[,suboptions] Image sequence templates. Each filename may be in the form of a template that specifies a sequence of image files. This option defines a template_name that may be used subsequently in place of any of the arguments infile1, ..., infileN, or outfile. template_name is a string with '#' characters designating integer indices to be filled in. The number of '#' characters indicates the minimum field length for each index; left padding with zeros is performed as needed in order to meet this minimum. By default, indices start at 0 and increment by 1 until either no more files exist (for inputs) or no more files need to be written (for outputs). A template may be customized using the suboptions described in the Template Suboptions section. If this option is not used, a filename with '#' characters is automatically interpreted as a template if the filename does not already exist as a regular file and, for outputs, if the selected file format is an image format. ------------ * EXAMPLES * ------------ Print help information. dmconvert -h Describe the input files. dmconvert -D -l in.aiff in.rgb in.movie in.mps Describe the digital media files in the current directory. dmconvert -D -s -q * Make an MPEG-1 audio bitstream from an AIFF audio file. dmconvert -f mpeg1a -p audio in.aiff out.mpa Make an audio/video SGI movie from an AIFF-C audio file and a video-only SGI movie. dmconvert -f sgimv -p audio -p video in.aifc in.movie out.movie Make a video-only QuickTime movie from an audio/video SGI movie. dmconvert -f qt -p video in.movie out.mov Make a sequence of SGI rgb files from the video track of an SGI movie. The output files will be named out00.rgb, out01.rgb, ... sh/csh: dmconvert -f rgb -p video -n out##.rgb in.movie out##.rgb ksh: dmconvert -f rgb -p video -n out####.rgb in.movie out####.rgb Please note that some shells such as ksh require escaping the # character. Make an AIFF audio file from a NeXT file and a WAVE file. Also describe the files and print progress information. dmconvert -f aiff -p audio -d -v in.next in.wave out.aiff FILE SUBOPTIONS The file suboptions are specified as a comma-separated list of subopt=value pairs. These provide additional information about the output file. The available suboptions are brate overall bitrate of the output file. Supported for files that use MPEG-1, Cinepak, or Cosmo JPEG compression. For files that contain only one track, this sets the bitrate of that track. loop default looping mode of the output movie during playback ("once", "loop", or "swing"). Supported for SGI movies. interleave granularity in seconds of audio and video interleaving. For example, to write audio and video in alternating chunks of duration 0.5 seconds each, use an interleave value of 0.5. Supported for SGI/QuickTime movies. paramfile parameter file for customizing outputs. Supported for MPEG-1 audio, video, and systems bitstreams. For an example, see /usr/lib/dmconvert/mpeg1.par. ------------ * EXAMPLES * ------------ Make an MPEG-1 video bitstream at 1.5 Mbps. dmconvert -f mpeg1v,brate=1500000 in.movie out.mpv Make an SGI movie with a specific looping mode and interleave. dmconvert -f sgimv,loop=swing,interleave=0.1 in.movie out.movie Make an MPEG-1 systems bitstream using a parameter customization file. dmconvert -f mpeg1s,paramfile=mpeg1.par in.movie out.mps AUDIO SUBOPTIONS The audio suboptions are specified as a comma-separated list of subopt=value pairs. These are used to configure the processing of audio data from input to output. Processing consists of a pipeline of individual conversion operations. Suboptions may be specified in any order, but the actual order of operations is given by byteord->rate->channels->pcmmap/format/width->compression The available suboptions are rate frame rate of the output audio track. If the input track has a different rate, automatic rate conversion is performed. For conversions between the standard rates, 8000, 11025, 16000, 22050, 32000, 44100, and 48000 Hz, high quality filters are used. For conversions with other rates, simple algorithms of lower quality are used. In the special case of converting from 8012.8210513 Hz audio (common in NeXT files) to a rate other than 8000 Hz, the input samples are automatically interpreted as 8000 Hz so that the high quality filters are used. To avoid this small pitch shift, first convert to an 8000 Hz sound track (the simple algorithm should be acceptable), then to the desired rate. stopatten stopband attenuation of the rate conversion filter (78.0, 96.0, or 120.0 dB); applies only to conversions between the standard rates. Higher values produce better quality but require more computation. transw transition bandwidth of the rate conversion filter (1.0, 10.0, or 20.0 percent); applies only to conversions between the stand- ard rates. Lower values produce better quality but require more computation. chan number of channels in the output audio track (1, 2, or 4). pcmmap PCM mapping of the output audio track. Value may take the form "slope/intercept/minclip/maxclip" or just "slope", which is equivalent to "slope/0/0/0". This maps output sample values to the range [intercept-slope,intercept+slope]. If minclip<maxclip, clipping to these limits is performed as well. format sample format in the output audio track ("2scomp", "unsigned", "float", or "double"). width sample width in the output audio track (1-32 bits). Not relevant for float or double sample formats. comp compression scheme to apply to the output audio track ("none", "g711a", "g711u", "g722", "g726", "g728", "gsm", "dvi", "mpeg1", or "multirate"). Supported for AIFF-C, NeXT/Sun, VOC, and WAVE files. Not every compression scheme is supported by each of these. brate bitrate to use for the output audio track. Supported for MPEG-1 compression. If the output file has only one track and the file bitrate suboption is also specified, the file bitrate takes precedence. layer encoding layer to use for MPEG-1 compression (1, 2). chanmode channel mode to use for MPEG-1 or Multirate compression ("stereo", "joint", or "dual"). Related channels should be encoded as "stereo" or "joint". The latter exploits inter- channel redundancy for better compression. Independent channels should be encoded as "dual". bratepol bitrate policy to use for MPEG-1 or Multirate compression ("fixed", "constqual", or "lossless"). MPEG-1 encoding may operate at either a fixed bitrate or constant quality. Multirate encoding may operate at either constant quality or in lossless mode. nmr noise-to-mask-ratio to use for constant quality MPEG-1 compression (-13.0 to 13.0 dB). Zero yields a theoretically imperceptible noise level. Positive values provide more compression but more noise, and negative values, vice versa. byteord byte ordering of the output audio track ("big" or "little" endian). Supported for uncompressed raw audio output. The following suboptions describe the input. inraw indicates whether the input files consist of raw audio data ("true" or "false"). If true, no other input file formats are recognized. indataoff,inframecnt the data offset in bytes from the beginning of file, and the total number of audio frames. Relevant only for raw audio inputs. inrate,inchan,informat,inwidth,incomp,inbyteord frame rate, channels, sample format, sample width, compression, and byte ordering of the input. Relevant only for raw audio inputs. inpcmmap the PCM mapping that describes the input sample range. Value is given in the same form as the output PCM mapping. Input clipping will be performed before main conversions such as frame rate, channels, etc. ------------ * EXAMPLES * ------------ Make a 32 KHz AIFF file from an 8KHz input using the highest quality rate conversion. dmconvert -f aiff -p audio,rate=32000,stopatten=120.0,transw=1.0 in.aiff out.aiff Make a two-channel AIFF file from a mono input. dmconvert -f aiff -p audio,chan=2 in.aiff out.aiff Make a NeXT file that has float samples. Scale the samples to the range [-5.0,5.0] and also clip values less than -4.5 and greater than 4.5. dmconvert -f next -p audio,format=float,pcmmap=5.0/0.0/-4.5/4.5 in.aiff out.next Make an AIFF file that has 8-bit twos-complement samples. dmconvert -f aiff -p audio,format=2scomp,width=8 in.aiff out.aiff Make an AIFF-C file that uses Layer II MPEG-1 compression at 192 Kbps, with the channels encoded under "joint" mode. dmconvert -f aifc -p audio,comp=mpeg1,brate=192000,layer=2,chanmode=joint in.aiff out.aifc Make an AIFF-C MPEG-1 file using constant quality encoding and a low noise-to-mask ratio. dmconvert -f aifc -p audio,comp=mpeg1,bratepol=constqual,nmr=-10.0 in.aiff out.aifc Make a file of raw audio samples that are written as little-endian. dmconvert -f rawaudio -p audio,format=2scomp,width=16,byteord=little in.aiff out.raw Make a WAVE audio file from raw input samples. The samples are extracted from the middle of the input file, and their characteristics are fully described. dmconvert -f wave -p audio,inraw=true,indataoff=100,inframecnt=4000, inrate=44100,inchan=2,informat=2scomp,inwidth=16,incomp=none, inbyteord=big,inpcmmap=30000 in.raw out.wave VIDEO SUBOPTIONS The video suboptions are specified as a comma-separated list of subopt=value pairs. These are used to configure the processing of video data from input to output. Processing consists of a pipeline of individual conversion operations. Suboptions may be specified in any order, but the actual order of operations is given by rate->interlace->layout/orientation->crop->filter->size->compression The available suboptions are rate frame rate of the output video track. If the input track has a different rate, automatic rate conversion is performed. ratecvt type of rate conversion to use ("rptdrp" or "inv32"). Repeat-drop is the simpler scheme. Inverse 3:2 pulldown may be used to convert 30 to 24 fps, or 29.97 to 23.976 fps. il interlacing of the output video track. May be "none" (non- interlaced), "even" (even lines temporally first), or "odd" (odd lines temporally first). ilcvt type of interlace conversion to use. Supported types are "pn_interfield" (odd/even parity to non-interlaced) A non-linear filter is applied between the fields for high quality de-interlacing. "pn_combine" (odd/even parity to non-interlaced) The fields are temporally combined without modification. "np_separate" (non-interlaced to odd/even parity) The fields are temporally separated without modification. "pp_swap" (odd to even parity, or vice versa) The fields are temporally swapped without modification. fl frame layout of the output video track. May be "full" (full frame) or "split" (split fields). The frame layout indicates how video lines are stored, and is not the same as interlacing, which indicates how the lines are temporally sampled. For example, interlaced video may be stored as full frames or split fields, whereas non-interlaced video is usually stored as full frames only. This suboption is supported for image files. For SGI movies, the frame layout is currently restricted to split fields for interlaced data and full frames for non-interlaced data, so the interlacing suboption also serves to specify the output frame layout. or orientation of images in output video track. May be "b2t" (bottom-to-top) or "t2b" (top-to-bottom). Supported for making SGI movies. cropl,cropr,cropt,cropb number of pixels to crop from left, right, top, and bottom borders of input images. For interlaced material, top and bottom cropping should be even numbers. filt filter to apply during conversion. The following values are recognized. "vblur" blur images with vertical 1-2-1 convolution, where the center tap corresponds to the field opposite to that of the outer taps. Useful for reducing flicker if output images are played back through video. Supported for making image files and SGI/QuickTime movies. "soft", "softmax" soften images with normal or maximum settings. Useful as a preprocessing step before compression. Supported for MPEG-1 movies. sx,sy,size size of output image in pixels. Supported for making image files and movies. sx and sy are used to specify individual dimensions. size is used to specify both dimensions, where the value is expressed as WxH (e.g. 640x480) or one of the strings "orig" or "sif". For interlaced material, the height should be an even number. lbox letterboxing flag ("true" or "false"). If false, the input images are scaled as needed to fill the output size, which may require different scale factors in each dimension. If true, a common scale factor is used and any remaining space is filled with black. Supported for making image files and SGI/QuickTime movies. comp compression scheme to apply to the output video track ("none", "jpeg", "mvc1", "mvc2", "qt_anim", "qt_video", "qt_cvid", "qt_mjpega", "rle", "rle24" or "huffyuv"). The Compact Video scheme, "qt_cvid", is also known as Cinepak. The "qt_mjpega" represents Quicktime's Motion JPEG Format A. Supported for SGI/QuickTime movies. SGI movies cannot use scheme's with the "qt_" prefix. engine engine used during the conversion ("cosmo" or "sw"). Supported for JPEG compression or decompression. brate bitrate to use for the output video track. Supported for MPEG-1, Cinepak, and Cosmo JPEG compression. If the output file has only one track and the file bitrate suboption is also specified, the file bitrate takes precedence. squal spatial quality factor used in compression (0.0 - 1.0). Supported for SGI/QuickTime movies. This is useful for setting the spatial quality of video tracks compressed with JPEG or a QuickTime scheme. tqual temporal quality factor used in compression (0.0 - 1.0). Supported for QuickTime movies. This is useful for setting the temporal quality of tracks compressed with a QuickTime scheme. kdist distance between key frames. Supported for QuickTime and MPEG-1 video compression schemes. For MPEG-1 this is equivalent to the N parameter, which gives the distance between I frames. rdist distance between reference frames. Supported for MPEG-1 video compression. This is equivalent to the M parameter, which gives the distance between I or P frames. For example, the pattern IBBPBBI (M=3,N=6), would be specified by rdist=3 and kdist=6. The following suboptions describe the input, and are useful for adding information about image files. inrate,inil,infl frame rate, interlacing, and frame layout of input images. inpixasp pixel aspect ratio of input images. This is a float defined as the vertical extent of a pixel divided by its horizontal extent. It may also be specified as one of the following strings - "sq" (square pixels), "c525" (CCIR601 525), or "c625" (CCIR601 625). Used in making SGI movies or MPEG-1 movies. ------------ * EXAMPLES * ------------ Make a 23.976 fps MPEG-1 video bitstream from a 29.97 fps SGI movie using inverse 3:2 pulldown. dmconvert -f mpeg1v -p video,rate=23.976,ratecvt=inv32 in.movie out.mpv Make a non-interlaced SGI movie from an even-interlaced SGI movie using interfield filtering. dmconvert -f sgimv -p video,il=none,ilcvt=pn_interfield in.movie out.movie Make a sequence of split field image files, out0.rgb, out1.rgb, ..., from an odd-interlaced SGI movie. dmconvert -f rgb -p video,fl=split -n out#.rgb in.movie out#.rgb Make a top-to-bottom SGI movie. dmconvert -f sgimv -p video,or=t2b in.movie out.movie Make an SGI movie by cropping, blurring, and resizing the input video. Use letterboxing during the resize. dmconvert -f sgimv -p video,cropl=10,cropr=10,filt=vblur,size=320x240, lbox=true in.movie out.movie Make an SGI movie with JPEG video at 10.0 Mbps, and use Cosmo to assist in the compression. dmconvert -f sgimv -p video,comp=jpeg,engine=cosmo,brate=10000000 in.movie out.movie Make a QuickTime Cinepak movie at specific spatial and temporal qualities. dmconvert -f qt -p video,comp=qt_cvid,squal=0.9,tqual=0.5 in.movie out.mov Make a QuickTime Motion JPEG Format A movie which has odd interlaced fields. This is a good format for cross-platform field based movies. dmconvert -f qt -p audio -p video,comp=qt_mjpega,il=odd movie out.mov Make an MPEG-1 systems bitstream with a video frame pattern IBBPBBI. The audio track is also written out. dmconvert -f mpeg1s -p audio -p video,kdist=6,rdist=3 in.movie out.mps Make an MPEG-1 video bitstream from the input image files in0.rgb, in1.rgb, ..., and provide information about the input data. dmconvert -f mpeg1v -p video,inrate=15.0,inil=even,infl=split, inpixasp=c525 -n in#.rgb in#.rgb out.mpv TEMPLATE SUBOPTIONS The template suboptions are specified as a comma-separated list of subopt=value pairs. These customize how the template name is expanded when it is used in place of a regular filename. The available suboptions are start starting index for the sequence of image files. end ending index for the sequence of image files. step increment to apply to the construction of indices. ------------ * EXAMPLES * ------------ Make an SGI movie from the images in.rgb.9, in.rgb.10, and in.rgb.11. dmconvert -f sgimv -n in.rgb.#,start=9,end=11,step=1 -p video in.rgb.# out.movie Make a sequence of ten SGI images from an input movie, and name them out01.rgb, out03.rgb, out05.rgb, ..., out19.rgb. dmconvert -f rgb -n out##.rgb,start=1,end=19,step=2 -p video in.movie out##.rgb CONVERSIONS WITH COSMO MOVIES dmconvert may be used to convert from movies recorded with the Cosmo Compress option board (cl_cosmo(3dm)), or to produce movies that are playable by Cosmo. Cosmo movies are just SGI movies with particular video characteristics. No special treatment is necessary to use these movies as input files, but certain settings are required for creating movies playable by Cosmo. The output video track should be constructed with comp=jpeg and or=t2b. Further, the dimensions, interlacing, and frame rate should match one of the following modes. width height interlacing frame rate ----- ------ ----------- ---------- NTSC 640 480 or 496 odd 29.97 CCIR601-525 720 480 or 496 odd 29.97 PAL 768 576 even 25 CCIR601-625 720 576 even 25 Half-widths and half-heights are also accepted in each mode. ------------ * EXAMPLES * ------------ Make an MPEG-1 movie from a Cosmo movie. dmconvert -vf mpeg1s -p audio -p video,sx=320,sy=240 cosmo.movie out.mps Make a QuickTime Cinepak movie from a Cosmo movie. dmconvert -vf qt -p audio -p video,comp=qt_cvid,sx=320,sy=240,rate=15.0 cosmo.movie out.mov Make a Cosmo movie from another SGI movie. dmconvert -vf sgimv -p audio -p video,comp=jpeg,or=t2b,sx=640,sy=480, il=odd,rate=29.97 in.movie cosmo.movie NOTES In order for some image files to be recognized, the filename should have an extension that matches the file format. For example, if a Targa file "foo" is not recognized, then rename it as "foo.tga". MacPaint image files are always written as 576x720. Alpha channel is supported only for SGI images and SoftImage PIC files. The "rgbA" output file format computes alpha based on pixel luminance. Some command-line syntax changes have been made since previous releases. o the "sgirgb" file format is still supported, but the new equivalent is "rgba". o the "-p all" option should no longer be used. This functionality is available from the "-f file_format", "-p audio", and "-p video" options. o the MPEG-1 "file" suboption is now called "paramfile". When reading TIFF images with 16 bits/component, the upper 8 bits are no longer ignored. Its possible to revert to the old behaviour by setting the environment variable DMCONVERT_DISABLE_SCALE. This version does not support writing DIF/DV files. A workaround is to generate a quicktime file and then convert that to DIF using a separate utility (such as the DVlink application included with the DVlink 1394 card). For MPEG-1 movies, the video size defaults to "sif" (320x240) if no other size param is specified. CAVEATS dmconvert relies on ImageVision for certain functionality. Prior to IRIX 6.5.25, dmconvert used the ImageVision 2.5 libraries, which rely on the DISPLAY environment variable. If the DISPLAY environment variable is set to a system that is down, dmconvert can hang for a long time prior to doing the conversion. A workaround for this is to set the DISPLAY environment variable to the local system, so that a connection can be made. This can be done as follows: sh : DISPLAY="0:0"; export DISPLAY csh : setenv DISPLAY 0:0 Note that versions of dmconvert shipped with IRIX 6.5.25 or later do not have this problem. MPEG CAVEATS When converting to MPEG-1 systems streams, conversion of large amounts of data (typically over 1 GB) stops with the following message: dmconvert: SGI Compression Library error. mux: buffer underflow; use higher systems bitrate Increasing the systems bitrate may or may not cause the problem to go away. If possible, breaking up the data into chunks and encoding them separately should work. AUTHOR Silicon Graphics Computer Systems. Portions developed at the San Diego Supercomputer Center. dmconvert uses the SGI Audio File, Compression, ImageVision, and Movie Libraries to access digital media data. Many of the image file formats are supported through the San Diego Supercomputer Center's image library (libim, libsdsc). This library is available from anonymous ftp at sdsc.edu in the /pub/sdsc/graphics/imtools/ directory. For more information, contact info@sdsc.edu. FILES /usr/lib/dmconvert/mpeg1.par -- sample mpeg1 parameter file SEE ALSO dminfo(1), dmplay(1), dmrecord(1), soundplayer(1), soundeditor(1), imgcopy(1), imginfo(1), imgview(1), imgworks(1), mediaconvert(1), movieplayer(1), capture(1), moviemaker(1), AFintro(3dm), CLintro(3dm), cl_cosmo(3dm), IL(3il), mvIntro(3dm), mpeg(4) Page 15