prevnext   » WIT: Wiimms ISO Tools » wit: Wiimms ISO Tool » wit convert

wit convert

Convert, scrub, join, split, compose, extract, patch, encrypt and decrypt Wii and GameCube disc images and replace the source with the result. Images, WBFS partitions and directories are accepted as source. The former command name was SCRUB. »wit CONVERT« is like »wit COPY« but removes the source and replace it with the new file if copying is successful. It have been implemented as replacement of the SCRUB command of other tools. »wit CONVERT« does more than only scrubbing and therefor it was renamed from 'SCRUB' to 'CONVERT', but the old command name is still allowed.

Contents

1.   Syntax

wit CONVERT source
wit CONVERT [[--source|--recurse] source]...

2.   Options

Options
Option Param Description
-t --test Run in test mode, modify nothing.

>>> USE THIS OPTION IF UNSURE! <<<

-T --titles file Read file for disc titles. -T0 disables titles lookup.
--utf-8 Enables UTF-8 support for filenames (default).
--no-utf-8 Disables UTF-8 support for filenames.
--lang lang Define the language for titles.
-s --source path Use the entered file or directory as source.

Directories are expanded to all containing files but hidden files (file names begins with a point) are ignored. If a command needs only images then non image files of the directory are ignored without notification. The option --no-expand suppress the directory expansion.

--no-expand Do not expand directories to the containing files or images. This option does not change the behavior of --recurse.
-r --recurse path If path is not a directory, then it is used as a simple source file like --source.

Directories are scanned for source files recursively. The option --rdepth limits the search depth. Hidden files and hidden sub directories (file names begins with a point) and files with non supported file types (non ISO files for most commands) are ignored without notification.

--rdepth depth Set the maximum recurse depth for option --recurse. The default search depth is 10.
-x --exclude id A comma separated list with ID4 and ID6 values is expected. '.' is a wildcard for exact 1 character and '+' is a wildcard for any number characters. If the parameter begins with a '@' the given file is read and each line is scanned for one ID. Images with the given ID are excluded from operation. Each use of this option expands the exclude list. See --include-first for precedence issues.
-X --exclude-path file_or_dir Scan the ID of the source and add it to the exclude list. If the source is a directory then scan all images of the directory. Images with the given ID are excluded from operation. Each use of this option expands the exclude list. See --include-first for precedence issues.
-n --include id A comma separated list with ID values is expected. '.' is a wildcard for exact 1 character and '+' is a wildcard for any number characters. If the parameter begins with a '@' the given file is read and each line is scanned for one ID. Only images with the given ID are included into the operation. Each use of this option expands the include list. See --include-first for precedence issues.
-N --include-path file_or_dir Scan the ID of the source and add it to the include list. If the source is a directory then scan all images of the directory. Only images with the given ID are included into the operation. Each use of this option expands the include list. See --include-first for precedence issues.
--include-first The options --include, --include-path, --exclude and --exclude-path decide which discs are included into the operation. If neither include nor exclude options are used, than all disc are included into the operation. If only include options are used, than only the specified discs are operated. If only exclude options are used, than all all discs but not the excluded are operated.

If include and exclude options are used together and --include-first is not set, than all discs are operated that are specified by any include option and not by any exclude option. If --include-first is set, than all discs are ignored that are specified by any exclude option and not by any include option.

-1 --one-job Execute only the first job and exit. This is a shortcut for »--job-limit 1«.
--job-limit num Execute only the first 'num' jobs and exit. If done without errors the exit status is OK (zero).
-i --ignore Ignore non existing files/discs without warning. If set twice then all non Wii and GameCube ISO images are ignored too.
--ignore-fst Disable composing and ignore FST directories as input.
--ignore-setup While composing ignore the file 'setup.txt', which defines some partition parameters.
--psel list This option set the scrubbing mode and defines, which disc partitions are handled. It expects a comma separated list of keywords, numbers and names; all together called parameter. All parameters are case insensitive and non ambiguous abbreviations of keywords are allowed.

Each parameter becomes a rule and each rule is appended to a rule list. Rules prefixed by a minus sign are DENY rules. Rules prefixed by a plus sign or without a prefix are ALLOW rules. Each partition is compared with each rule until a rule matches the partition. If a match it found, the partition is enabled for a ALLOW rule or disabled for a DENY rule.

The allowed keywords are: DATA, UPDATE, CHANNEL, PTAB0 .. PTAB3, ID, ALL, WHOLE and RAW. The following input formats are accepted too: ptype, #index, #<index, #<=index, #>index, #>=index and #tab_index.part_index.

--raw Abbreviation of »--psel RAW«.
-q --quiet Be quiet and print only error messages.
-v --verbose Be verbose and print more progress information. Multiple usage is possible: Progress counter is enabled if set at least two times. Extended logging is enabled if set at least four times. The impact of the other verbose levels are command dependent.
-L --logging This debug option enables the logging of internal memory maps. If set twice second level memory maps are printed too.
-P --progress Print progress counter independent of verbose level.
--scan-progress Print a message for each found image while scanning the file system.
--sections Print in machine readable sections and parameter lines.
--enc encoding Define the encoding mode. The mode is one of NONE, HASHONLY, DECRYPT, ENCRYPT, SIGN or AUTO. The case of the keywords is ignored. The default mode is 'AUTO'.
--modify list This patching option defines the impact of the options --name and --id. It expects a comma separated list of the following keywords (case ignored) as parameter: NONE, DISC, BOOT, TICKET, TMD, WBFS, TT, ALL and AUTO (default).

All keywords can be prefixed by '+' to enable that option, by a '-' to disable it or by a '=' to enable that option and disable all others.

--name name This patching option changes the name (disc title) of the disc to the given parameter. Up to 63 characters are expected. The disc header and boot.bin are objects to modify. The option --modify selects the objects.
--id id This patching option changes the ID of the disc to the given parameter. 1 to 6 characters are expected. Only defined characters not equal '.' are modified. The plus sign '+' is a wildcard for multiple '.' to fill the complete entered ID to 6 characters. The disc header, boot.bin, ticket.bin and tmd.bin are objects to modify. The option --modify selects the objects.
--disc-id id This patching option changes the ID of the disc header to the given parameter. 1 to 6 characters are expected. Only defined characters not equal '.' are modified. The plus sign '+' is a wildcard for multiple '.' to fill the complete entered ID to 6 characters. Option --disc-id overrides the definition of option --id.
--boot-id id This patching option changes the ID of boot.bin to the given parameter. 1 to 6 characters are expected. Only defined characters not equal '.' are modified. The plus sign '+' is a wildcard for multiple '.' to fill the complete entered ID to 6 characters. Option --boot-id overrides the definition of option --id.
--ticket-id id This patching option changes the ID of ticket.bin to the given parameter. 1 to 4 characters are expected. Only defined characters not equal '.' are modified. The plus sign '+' is a wildcard for multiple '.' to fill the complete entered ID to 4 characters. Option --ticket-id overrides the definition of option --id.
--tmd-id id This patching option changes the ID of tmd.bin to the given parameter. 1 to 4 characters are expected. Only defined characters not equal '.' are modified. The plus sign '+' is a wildcard for multiple '.' to fill the complete entered ID to 4 characters. Option --tmd-id overrides the definition of option --id.
--tt-id id This is a short cut for »--ticket id --tmd id«. If TICKET and TMD differ, the game will freeze after loading. So it make sense to change only TICKET and TMD IDs together.
--wbfs-id id This patching option changes the ID of the WBFS header to the given parameter if adding a file to a WBFS or if creating a WBFS file. 1 to 6 characters are expected. The already patched disc ID of the source is used as base and only defined characters not equal '.' are modified. The plus sign '+' is a wildcard for multiple '.' to fill the complete entered ID to 6 characters. Option --wbfs-id overrides the definition of option --id.
--region region This patching option defines the region of the disc. The region is one of JAPAN, USA, EUROPE, KOREA, FILE or AUTO (default). The case of the keywords is ignored. Unsigned numbers are also accepted.
--common-key index This patching option defines the common key index as part of the TICKET. Keywords 0, STANDARD, 1 and KOREAN are accepted.
--ios ios This patching option defines the system version (IOS to load) within TMD. The format is 'HIGH:LOW' or 'HIGH-LOW' or 'LOW'. If only LOW is set than HIGH is assumed as 1 (standard IOS).
--rm-files ruleset This patching option defines filter rules to remove real files and directories from the FST of the DATA partition. Fake signing of the TMD is necessary. The processing order of file options is: »--rm-files --zero-files --ignore-files«.
--zero-files ruleset This patching option defines filter rules to zero (set size to zero) real files of the FST of the DATA partition. Fake signing of the TMD is necessary. The processing order of file options is: »--rm-files --zero-files --ignore-files«.
--ignore-files ruleset This option defines filter rules to ignore real files of the FST of the DATA partition. Fake signing is not necessary, but the partition becomes invalid, because the content of some files is not copied. If such file is accessed the Wii will halt immediately, because the verification of the check sum calculation fails. The processing order of file options is: »--rm-files --zero-files --ignore-files«.
--align-part size If creating or moving partitions the beginning of each partition is set to an offset that is a multiple of the align size. Size must be a power of 2 and at least 32 KiB (=default).
--align-files If creating a partition the file 'align-files.txt' is read. Files listed with values >=0x8000 (Wii sector size) are automatically aligned to 0x8000.
--auto-split Enable auto split modus: Split only if necessary and determine the split size automatically.

THIS OPTION IS EXPERIMENTAL. In future versions it becomes the default.

--no-split Disable output file splitting. This is the default, but in future versions, the new option --auto-split becomes the default.
-z --split Enable output file splitting. The default split size is 4 GB.
-Z --split-size sz Enable output file splitting and define a split size. The parameter 'sz' is a floating point number followed by an optional unit factor (one of 'cb' [=1] or 'kmgtpe' [base=1000] or 'KMGTPE' [base=1024]). The default unit is 'G' (GiB).
--disc-size size Define a minimal (virtual) ISO disc size.
--prealloc [=mode] This option enables or disables the disc space preallocation. If enabled the tools try to allocate disc space for the new files before writing the data. This reduces the fragmentation but also disables the sparse effect for preallocated areas.

The optional parameter decides the preallocation mode: OFF (or 0), SMART (or 1), ALL (or 2). If no parameter is set, ALL is used.

Mode 'OFF' disables the preallocation. Mode 'SMART' looks into the source disc to find out the writing areas. SMART is only available for ISO, CISO and WBFS file types. For other file types ALL is used instead. Mode 'ALL' (the default) preallocate the whole destination file. Because of the large holes in plain ISO images, the SMART mode is used for ISOs instead.

--trunc Truncate a PLAIN ISO images to the needed size while creating.
--chunk-mode mode Defines an operation mode for --chunk-size and --max-chunks. Allowed keywords are 'ANY' to allow any values, '32K' to force chunk sizes with a multiple of 32 KiB, 'POW2' to force chunk sizes >=32K and with a power of 2 or 'ISO' for ISO images (more restrictive as 'POW2', best for USB loaders). The case of the keyword is ignored. The default key is 'ISO'.

--chm is a shortcut for --chunk-mode.

--chunk-size sz Define the minimal chunk size if creating a CISO or WIA file (for WIA details see option --compression}). The default is to calculate the chunk size from the input file size and find a good value by using a minimal value of 1 MiB for »--chunk-mode ISO« and 32 KiB for modes 32K and POW2. For the modes ISO and POW2 the value is rounded up to the next power of 2. This calculation also depends from option --max-chunks.

The parameter 'sz' is a floating point number followed by an optional unit factor (one of 'cb' [=1] or 'kmgtpe' [base=1000] or 'KMGTPE' [base=1024]). The default unit is 'M' (MiB). If the number is prefixed with a '=' then options --chunk-mode and --max-chunks are ignored and the given value is used without any rounding or changing.

If the input file size is not known (e.g. reading from pipe), its size is assumed as 12 GiB.

--chs is a shortcut for --chunk-size.

--max-chunks n Define the maximal number of chunks if creating a CISO file. The default value is 8192 for »--chunk-mode ISO« and 32760 (maximal value) for all other modes. If this value is set than the automatic calculation of --chunk-size will be modified too.

--mch is a shortcut for --max-chunks.

--compression mode Select one compression method, level and chunk size for new WIA files. The syntax for mode is: [method] [.level] [@factor]

'method' is the name of the method. Possible compressions method are NONE, PURGE, BZIP2, LZMA and LZMA2. There are additional keywords: DEFAULT (=LZMA.5@20), FAST (=BZIP2.3@10), GOOD (=LZMA.5@20) BEST (=LZMA.7@50), and MEM (use best mode in respect to memory limit set by --mem). Additionally the single digit modes 0 (=NONE), 1 (=fast LZMA) .. 9 (=BEST)are defined. These additional keywords may change their meanings if a new compression method is implemented.

'.level' is a point followed by one digit. It defines the compression level. The special value .0 means: Use default compression level (=.5).

'@factor' is a factor for the chunk size. The base size is 2 MiB. The value @0 is replaced by the default factor @20 (40 MiB). If the factor is not set but option --chunk-size is set, the factor will be calculated by using a rounded value of that option.

All three parts are optional. All default values may be changed in the future. --compr is a shortcut for --compression and --wia=mode a shortcut for »--wia --compression mode«. The command »wit COMPR« prints an overview about all compression modes.

--mem size This option defines a memory usage limit for compressing files (in MiB if no other unit is entered). When compressing a file with method MEM (see --compression) the the compression method, level and chunk size are selected with respect to this limit.

If this option is not set or the value is 0, then the environment WIT_MEM is tried to read instead. If this fails, the tool tries to find out the total memory by reading /proc/meminfo. The limit is set to 80% of the total memory minus 50 MiB.

-p --preserve Preserve file times (atime+mtime) while copying an image. This option is enabled by default if an unmodified disc image is copied.
-W --wdf [=param] Set the image output file type to WDF (Wii Disc Format). The output format is either WDFv1 or WDFv2. It depends of the input file format and of the aligning. --wdf=param is a short cut for »--wdf --align-wdf=param«.
--wdf1 [=param] Set image output file type to WDF and force version 1. --wdf1=param is a short cut for »--wdf1 --align-wdf=param«.
--wdf2 [=param] Set image output file type to WDF and force version 2. --wdf2=param is a short cut for »--wdf2 --align-wdf=param«.
--align-wdf [align][,minhole] Parameter align defines the aligning factor for new WDF images. It must be a power of 2 and smaller or equal than 1 GiB. The default WDF alignment is 1 for WDF v1 and 4 for WDF v2. Usual values are 1, 512, 4K and 32K.

The optional parameter minhole defines the minimal hole size, before a new chunk is created. If NULL, an internal value is used to minimize the total file size. minhole can't be smaller than align.

-I --iso Set image output file type to PLAIN ISO.
-C --ciso Set image output file type to CISO (Compact ISO, same as WBI).
-B --wbfs Set image output file type to WBFS (Wii Backup File System, default).
--wia [=compr] Set image output file type to WIA (Wii ISO Archive). The optional parameter is a compression mode and --wia=mode is a shortcut for »--wia --compression mode«.
-G --gcz Set image output file type to GCZ (Dolphins GameCube Zip).
--gcz-zip If creating a GCZ image, a blockwise z-compression is tried. If the compressed data is larger than 98.5%, the uncompressed data is stored. Encrypted blocks are stored directly as uncompressed data, because the 98.5% test fails all the time.

Option --gcz-zip disables this optimization for encrypted data and makes the creation process slower.

--gcz-block size The value defines the block size, if creating a GCZ image. The default is 16K (also Dolphins default). Smaller values enlarge the managment data and reduce the compression ratio. Use the option with caution!
The command CONVERT reorganize all given source files. Each source, that is a Wii or GameCube disc image (ISO image), is candidate for copying. Each candidate is copied to a temporary file, then the source is removed and the temporary file is renamed to the source file. SCRUB is an old and obsolete alternative name for CONVERT.

Non ISO files are ignored with a warning. The option --ignore suppresses this warning.

The output is scrubbed. The scrubbing can be controlled or disabled with the options --psel and --raw. The options --split and --split-size control the splitting.

While copying the some parts of the disc content can be patched. The option --psel can remove partitions. The options --id, --name, --region, --ios and --common-key change importand values of the disc and of the data partition. The options --rm-files and --zero-files manipulate the filesystem of the data partition. The option --enc controls the encryption of all partitions. See »Patching and composing options« for details. The command »wit EDIT« can patch a image in place without copying.

The output file format can be selected by option or filename. The destination filename can be filled with esacpe sequences to generate content dependent filenames. See »Writing an image« for details.

The option --test enables test mode: No files are written or removed. If --test is set at least two times a source list with a trailing destination will be printed.

2.1   See also

»wit COPY«   »wit EDIT«   »wit MOVE«

3.   Usual error/exit codes:

0 == OK      : all done without errors.
SYNTAX ERROR : at least one syntax error in command line found.
READ ERROR   : error while reading a file.
WRITE ERROR  : error while writing a file.
CANT CREATE  : Can't create output file.