Difference between revisions of "Thwimp"

From Custom Mario Kart
Jump to navigation Jump to search
m (Added Thwimp_CLI image to Media section)
Line 6: Line 6:
 
| [[MrTamkis]]
 
| [[MrTamkis]]
 
|-
 
|-
! Operating Systems:
+
! Operating system:
 
| Windows
 
| Windows
 
|-
 
|-
Line 12: Line 12:
 
| Visual Basic
 
| Visual Basic
 
|-
 
|-
! Software Type:
+
! Software type:
| Decoder and encoder
+
| Decoder/Encoder
 
|-
 
|-
! File Formats:
+
! File formats:
|  
+
|
 
* [[THP]]
 
* [[THP]]
 
* MP4
 
* MP4
Line 24: Line 24:
 
* INI
 
* INI
 
|-
 
|-
! Current Version:
+
! Version:
 
| v1.2
 
| v1.2
 
|-
 
|-
! Date of Release:
+
! Date of latest version:
| 2020-08-01
+
| 2020-08-03
 
|-
 
|-
 
! Website:
 
! Website:
 
| [http://www.eaglesoftltd.com/retro/Nintendo-Wii/thwimp EagleSoft Ltd]
 
| [http://www.eaglesoftltd.com/retro/Nintendo-Wii/thwimp EagleSoft Ltd]
 
|-
 
|-
! Source Code:
+
! Source code:
 
| [https://github.com/Tamk1s/Thwimp GitHub]
 
| [https://github.com/Tamk1s/Thwimp GitHub]
 
|-
 
|-
! User's Manual:
+
! User's manual:
 
| [https://github.com/Tamk1s/Thwimp/blob/master/README.md GitHub Manual]
 
| [https://github.com/Tamk1s/Thwimp/blob/master/README.md GitHub Manual]
 
|-
 
|-
! Downloads:
+
! Download:
| [http://www.mediafire.com/file/n82zcc05aarb6as/Thwimp_v1p2F.7z/file Thwimp]<br>
+
| [https://mediafire.com/?n82zcc05aarb6as MediaFire]
[https://ffmpeg.zeranoe.com/builds/ FFMPEG]<br>
 
[https://www.irfanview.com/main_download_engl.htm IrfanView 32-bit]<br>
 
THPConv
 
 
|}
 
|}
  
'''Thwimp''' is a tool for handling [[THP]] files within [[Mario Kart Wii]], especially those used in the menus.
+
== Overview ==
 +
'''Thwimp''' is a program created by [[MrTamkis]]. This is a Windows utility which allows users to easily view, rip and encode Nintendo [[THP]] video files for [[Mario Kart Wii]] and other [[GCN]]/[[Wii]] games, to an extent. Written in Visual Basic, the application calls some FOSS and other command line tools (not included) "from arms length" via the Command Prompt to perform its tasks.
  
== Introduction ==
+
Specifically, Thwimp uses:
'''Thwimp''' is a Windows utility which allows users to easily view, rip and encode Nintendo THP video files for Mario Kart Wii (and for other [[GCN]]/[[Wii]] games, to an extent). Written in Visual Basic, the Thwimp application calls some FOSS and other command line tools '''(not included)''' "from arms length" via the Command Prompt to perform its tasks.
 
  
'''Specifically, Thwimp uses:'''
+
* '''[https://ffmpeg.org FFMPEG]'''
 
 
* '''[https://www.ffmpeg.org FFMPEG]'''
 
 
** Video processing
 
** Video processing
* '''[https://www.ffmpeg.org FFPlay]'''
+
* '''[https://ffmpeg.org FFPlay]'''
 
** THP playback
 
** THP playback
* '''[https://www.irfanview.com IrfanView]'''
+
* '''[https://irfanview.com IrfanView]'''
 
** Image conversion
 
** Image conversion
 
** BMP to JPG conversion
 
** BMP to JPG conversion
Line 63: Line 58:
 
*** Standard, non-progressive JPG files
 
*** Standard, non-progressive JPG files
 
* '''THPConv'''  
 
* '''THPConv'''  
** '''Definitely not included!'''
+
** Encoding JPG frames and WAV file into THP videos
** Encoding JPG frames + WAV file into THP videos
 
  
Thwimp can show the hard-coded information about how each THP file is formatted in Mario Kart Wii. Thwimp can also view Mario Kart Wii's THP files, as well as convert them to everyday video files. It can crop the THP video files to a particular subvideo cell and time period, and then convert them to MP4 (H.264 codec) video files, to WAV files (for videos with audio), and padding to BMP files.
+
Thwimp can show the hard-coded information about how each THP file is formatted in Mario Kart Wii. Thwimp can also view Mario Kart Wii's THP files, as well as convert them to regular video files. It can crop the THP video files to a particular subvideo cell and time period, and then convert them to MP4 (H.264 codec) video files, to WAV files (for videos with audio) and padding to BMP files.
  
The THP video files for menus in Mario Kart Wii tend to be an array of multiple subvideo cells inside, with each cell playing back several other videos in multiple time chunks ("multiplicities"). As required by the file format specification, THP video files must have their dimensions be a multiple of 16px. Often times the size of the subvideo array will '''not''' be enough to meet the specification, so padding is added to the bottom of the THP video. This padding is not only used to meet the specification, but is sometimes also used for control information. For example, some of the videos shown during menus will have a white rectangle move at integral positions at each multiplicity within this padding area. This white rectangle controls which row in a menu is highlighted during THP playback, for synchronization purposes.
+
The THP video files for menus in Mario Kart Wii tend to be an array of multiple subvideo cells inside, with each cell playing back several other videos in multiple time chunks ("multiplicities"). As required by the file format specification, THP video files must have their dimensions be a multiple of 16px. Often times, the size of the subvideo array will '''not''' be enough to meet the specification, so padding is added to the bottom of the THP video. This padding is not only used to meet the specification, but is sometimes also used for control information. For example, some of the videos shown during menus will have a white rectangle move at integral positions at each multiplicity within this padding area. This white rectangle controls which row in a menu is highlighted during THP playback, for synchronization purposes.
  
Thwimp can intelligently handle audio, the subvideo array, multiplicity, and padding/control information when encoding THP files to replace the ones in-game. It does this by accepting appropriately named, input MP4 video files for each subvideo cell in the array, and for each multiplicity. Where applicable, it will also accept a WAV audio file, and BMP image frames for each multiplicity's padding/control signal as needed. After reading the input files, Thwimp will intelligently process and compose all of the files together appropriately, in order to create a high-quality, properly formatted THP video replacement file.
+
Thwimp can intelligently handle audio, the subvideo array, multiplicity, and padding/control information when encoding THP files to replace the ones in-game. It does this by accepting appropriately named, input MP4 video files for each subvideo cell in the array and for each multiplicity. Where applicable, it will also accept a WAV audio file, and BMP image frames for each multiplicity's padding/control signal as needed. After reading the input files, Thwimp will intelligently process and compose all of the files together appropriately, in order to create a high-quality, properly formatted THP video replacement file.
  
 
== Main Features ==
 
== Main Features ==
 
* '''Hybrid GUI/CLI application'''
 
* '''Hybrid GUI/CLI application'''
* '''View the hard-coded stat information for each THP file in the original Mario Kart Wii game:'''
+
* '''View the hard-coded stat information for each THP file in the original Mario Kart Wii game'''
* '''Playback THP files from the original game.'''
+
* '''Playback THP files from the original game'''
* '''Convert THP files into normal video files:'''
+
* '''Convert THP files into normal video files'''
 
** Rip a particular subvideo/multiplicity within the THP file:
 
** Rip a particular subvideo/multiplicity within the THP file:
 
*** Crop video to a particular size relative to a particular position.
 
*** Crop video to a particular size relative to a particular position.
Line 83: Line 77:
 
** Convert video stream in THP file to MP4 (H.264 encoded).
 
** Convert video stream in THP file to MP4 (H.264 encoded).
 
** Convert audio stream in THP file to WAV file.
 
** Convert audio stream in THP file to WAV file.
* '''Encode new, replacement THP files:'''
+
* '''Encode new, replacement THP files'''
 
** Transform input files into a final THP video:
 
** Transform input files into a final THP video:
 
*** Select individual MP4 input video files for each subvideo cell/multiplicity.
 
*** Select individual MP4 input video files for each subvideo cell/multiplicity.
Line 93: Line 87:
 
*** Used to truncate the subvideo length to an exact frame count, if some of the subvideos' length > target limit.
 
*** Used to truncate the subvideo length to an exact frame count, if some of the subvideos' length > target limit.
 
* '''Ability to load different Thwimp data filesets'''
 
* '''Ability to load different Thwimp data filesets'''
** Used to allow Thwimp to handle THPs from other games
+
** Used to allow Thwimp to handle THPs from other games.
** Detailed documentation on the fileset formats
+
** Detailed documentation on the fileset formats.
 
* '''Ability to save/load settings to/from a settings INI file'''
 
* '''Ability to save/load settings to/from a settings INI file'''
 
* '''Progress bars to detail current progress and task being worked on'''
 
* '''Progress bars to detail current progress and task being worked on'''
Line 101: Line 95:
 
** Encoding
 
** Encoding
 
* '''Built-in logger for debugging and error-reporting'''
 
* '''Built-in logger for debugging and error-reporting'''
** Ability to save log to a file
+
** Ability to save log to a file.
 
 
  
 
== Usage ==
 
== Usage ==
 
Please read the '''[https://github.com/Tamk1s/Thwimp/blob/master/README.md manual]''' for full usage of the application.
 
Please read the '''[https://github.com/Tamk1s/Thwimp/blob/master/README.md manual]''' for full usage of the application.
 
You will need the following applications installed, and point to their installation paths as necessary in the Options tab:
 
* [https://www.ffmpeg.org/ FFMPEG] for video processing
 
* [https://www.ffmpeg.org/ FFPlay (included with FFMPEG)]
 
* [https://www.irfanview.com/ IrfanView 32-bit]
 
* THPConv
 
  
 
== Media ==
 
== Media ==
 +
{{youtube-box|tutorial|WMLOtY16AtA|v1.1 Update|height=300}}
 +
{{youtube-box|tutorial|IINyrm6pJBg|v1.0 Release/Tutorial|height=300}}
 
<gallery>
 
<gallery>
 
File:Thwimp_TabTHP.jpg|Main tab of program (THP)
 
File:Thwimp_TabTHP.jpg|Main tab of program (THP)
Line 119: Line 108:
 
File:Thwimp_Playback_BCS.jpg|THP Playback of battle_course_select.thp
 
File:Thwimp_Playback_BCS.jpg|THP Playback of battle_course_select.thp
 
File:Thwimp_CLI.jpg|Thwimp Command Line syntax
 
File:Thwimp_CLI.jpg|Thwimp Command Line syntax
 
 
</gallery>
 
</gallery>
{{youtube-box|tutorial|WMLOtY16AtA|v1.1 Update (new THP Viewer/Decoder features)|height=300}}
 
{{youtube-box|tutorial|IINyrm6pJBg|v1.0 Release/Tutorial|height=300}}
 
  
 
== Version History ==
 
== Version History ==
 
{| class="wikitable"
 
{| class="wikitable"
|-
+
! Version
! align=left| Version
+
! Date of release
! align=left| Date of release
+
! Information
! align=left| Information
 
 
|-
 
|-
 
| v1.0
 
| v1.0
Line 137: Line 122:
 
| v1.1
 
| v1.1
 
| 2019-01-07
 
| 2019-01-07
| Update:
+
|
* Bug fixes:
+
* Fixed THP Encoding framerate bug.
** Fixed THP Encoding framerate bug.
+
* Fixed bug with ripping control signal frames from battle_cup_select.thp being off by one multiplicity.
** Fixed bug with ripping control signal frames from<br>battle_cup_select.thp being off by one multiplicity.
+
* Refactored THP Viewer/Ripper UX with the ability to rip individual subvideo cells/multiplicities.
* Enhancements:
+
* Added redirect to this page.
** Refactored THP Viewer/Ripper UX with the ability to rip individual subvideo cells/multiplicities.
 
* Added this CTWiiki page.
 
 
|-
 
|-
 
| v1.2
 
| v1.2
| 2020-08-01
+
| 2020-08-03
| Update:
+
|
* '''Bug fixes:'''
+
* Fixed serious, application-breaking bug where pointing to a real i_view32.exe IrfanView executable would cause the THP Encoder process to fail.
** Fixed serious, application-breaking bug where pointing to a real i_view32.exe Irfanview executable would cause the THP Encoder process to fail
+
* Optimized THP encoding, especially when handling videos requiring dummy/control padding.
*** Bug would convert the ripped BMP frames from the final generated video to Progressive JPG files
+
* Fixed error parsing String datatype into Single datatype when in a foreign culture.
*** THPConv cannot handle Progressive JPG markers (SOF2 header of $FFC2), so this bug would cause '''THP conversion to fail'''
+
* Fixed KeepInRange() function parsing bugs.
** Optimized THP encoding, especially when handling videos requiring dummy/control padding
+
* Fixed lingering file I/O from StreamReaders/Writers.
*** Issue would cause the conversion of each multiplicities' dummy frame (dummy_N.bmp) into a dummy multiplicity video (dummy_N.mp4) to be poor, with their frame counts far exceeding their intended value
+
* Added an additional dummy entry as 0th entry in default Mario Kart Wii data files.
*** Issue would snowball further along the THP encoding process, and cause the final video to be much larger in framecount than expected
+
* Enhanced and improved GUI.
*** This would, in turn, slow down the process of ripping BMP frames and converting to JPG frames for the actual THP encoding
+
* Enhanced Thwimp CLI.
**** Application deletes all JPG files above the expected framecount limit before doing the encoding, so many CPU cycles would be wasted without the bugfix
+
* Enhanced THP Viewer/Ripper.
*** Issue fixed with a more efficient FFMPEG command line call when handling dummy padding
+
* Added new options.
** Error parsing String datatype into Single datatype when in a foreign culture
+
* Added audio to application.
*** Issue affected proper reading of FPS value for a THP file from the Thwimp data fileset
+
* Added progress bars/application logger.
*** Caused by foreign cultures expecting a decimal such as "12,34" instead of "12.34" for decimal values
 
*** Fixed by forcing culture-invariant (EN-US) format for decimals ("12.34")
 
** KeepInRange() function parsing bugs
 
*** Fixed issue where, in the THP Viewer/Ripper section, "Error Parsing String into <T>" errors will throw under the following conditions
 
**** If a MaskedTextBox is focused on
 
**** If MaskedTextBox cleared to empty (underscores)
 
**** If the user focuses elsewhere
 
*** Fixed by less over-zealous error-trapping, to prevent false positives
 
** Lingering file I/O from StreamReaders/Writers
 
*** Added proper closing of StreamReaders/Writers, regardless of whether successful usage or failure due to Try-Catch errors
 
*** This properly
 
**** Closes file I/O handles on files, in case of error and application is then quit
 
**** Unlocks them for everyday user file operations afterwards
 
** Added an additional dummy entry as 0th entry in default MKWii data files
 
 
 
* '''Enhancements:'''
 
** Enhanced, improved GUI
 
** Thwimp CLI
 
*** Implemented command-line interface into Thwimp!
 
*** Redirected all stdout from the application's console into the calling Command Prompt
 
** THP Viewer/Ripper enhancements
 
*** Modified the THP Viewer playback so that it
 
**** Applies the crop settings (both physical and time) to the playback
 
**** Now properly trims any audio streams for playback of applicable THP videos!
 
***** This is done via ripping audio and video streams separately (temporary MP4 files with only one stream type), trimming both, and merging both back into a final, temporary mp4 video file
 
***** Playback final temporary mp4 video file with the trimming applied
 
***** Temporary files generated in FFPlay WorkDir (new Options directory setting)
 
*** Modified THP Ripper so that it now properly trims any ripped audio streams for applicable THP videos!
 
** New Options
 
*** Fileset data
 
**** FileSet.txt file
 
***** Informational file which lists this fileset's
 
****** Game
 
****** Desc
 
****** Author
 
****** Version
 
****** Creation date
 
***** Data is displayed in new fields within Options tab
 
**** Updated default Mario Kart Wii Thwimp fileset with the new file
 
*** Paths
 
**** FFPlay WorkDir
 
***** Working directory for FFPlay temporary files
 
***** Used when viewing/ripping THP files having both an audio and video stream, when trimming time
 
**** DataFile Dir
 
***** Directory to use containing a data fileset to use for Thwimp (e.g. customization to use for other games)
 
*** Option flags (in Options tab)
 
**** "Audio" checkbox
 
***** Toggles audio
 
**** "Elevator Music" checkbox
 
***** Toggle THP Encoder elevator music
 
**** "Less MsgBox" checkbox
 
***** Supresses most informational MsgBoxes during THP Encoding processes
 
***** Prevents interruption for this long process
 
**** "Full Logs" checkbox
 
***** Logs '''everything''' (including stdout from Process command line calls)
 
**** Settings INI file
 
***** Buttons to save/load a Thwimp INI settings file
 
***** Allows for saving/loading of settings
 
*** New Help/Resources subsection
 
**** Added new section with various buttons to launch URLs in default browser with Thwimp resources
 
**** Buttons
 
***** Webpage
 
****** [http://www.eaglesoftltd.com/retro/Nintendo-Wii/thwimp EagleSoft Ltd webpage]
 
***** About
 
****** Application about box
 
***** MKWiiki Article
 
***** Manual (Github)
 
****** [https://github.com/Tamk1s/Thwimp/blob/master/README.md GitHub Manual]
 
***** Latest Release
 
****** [https://github.com/Tamk1s/Thwimp/releases GitHub Releases page]
 
***** Cmdline
 
****** Details valid command-line options for application (for CLI mode)
 
** Added audio to application
 
*** Custom error sound effect (SMB1 Mario death)
 
*** Custom success sound effect (SMB1 flagpole)
 
*** Elevator Music
 
**** Looping song BGM to play during long THP Encoding process
 
**** Song.wav at application directory
 
**** Audio toggle via new "Elevator Music" checkbox in Options tab
 
*** Audio toggle via new "Audio" checkbox in Options tab
 
** Progress bars/application Logger
 
*** Progress bars
 
**** Added a "Progress" section in THP tab, showing status of processes
 
***** 2 progress bar groups
 
****** Total
 
******* Overall progress
 
****** Current
 
******* Progress for a particular chunk within total progress
 
******* Similar to those old Installshield wizards from Windows 95, with multiple progress bars
 
****** Elements within a progress bar group
 
******* Textbox (logs progress messages)
 
******* Progress bar
 
******* Label (display current progress as percentage)
 
***** Refactored and improved THP Encoding process
 
**** Displays total/current THP viewer, ripping, and encoding progress
 
*** Application Logger
 
**** Added new "Log" group box section
 
**** Logs various messages
 
***** Application messages
 
***** Total/Current progress bar messages
 
***** MsgBox messages (and icons)
 
**** Control buttons
 
***** Cls
 
****** Clears various log elements
 
******* Total/current progress bar elements
 
******* Main Logger box
 
***** Save
 
****** Saves log to a file (for error reporting/debugging)
 
 
|}
 
|}
  
 
{{User-MrTamkis-Link}}
 
{{User-MrTamkis-Link}}
 
[[Category:Software]]
 
[[Category:Software]]

Revision as of 06:40, 4 August 2020

Thwimp
Thwimp Logo.png
Author: MrTamkis
Operating system: Windows
Programming language: Visual Basic
Software type: Decoder/Encoder
File formats:
  • THP
  • MP4
  • WAV
  • BMP
  • JPG
  • INI
Version: v1.2
Date of latest version: 2020-08-03
Website: EagleSoft Ltd
Source code: GitHub
User's manual: GitHub Manual
Download: MediaFire

Overview

Thwimp is a program created by MrTamkis. This is a Windows utility which allows users to easily view, rip and encode Nintendo THP video files for Mario Kart Wii and other GCN/Wii games, to an extent. Written in Visual Basic, the application calls some FOSS and other command line tools (not included) "from arms length" via the Command Prompt to perform its tasks.

Specifically, Thwimp uses:

  • FFMPEG
    • Video processing
  • FFPlay
    • THP playback
  • IrfanView
    • Image conversion
    • BMP to JPG conversion
      • Custom JPG Quality setting applied
      • Standard, non-progressive JPG files
  • THPConv
    • Encoding JPG frames and WAV file into THP videos

Thwimp can show the hard-coded information about how each THP file is formatted in Mario Kart Wii. Thwimp can also view Mario Kart Wii's THP files, as well as convert them to regular video files. It can crop the THP video files to a particular subvideo cell and time period, and then convert them to MP4 (H.264 codec) video files, to WAV files (for videos with audio) and padding to BMP files.

The THP video files for menus in Mario Kart Wii tend to be an array of multiple subvideo cells inside, with each cell playing back several other videos in multiple time chunks ("multiplicities"). As required by the file format specification, THP video files must have their dimensions be a multiple of 16px. Often times, the size of the subvideo array will not be enough to meet the specification, so padding is added to the bottom of the THP video. This padding is not only used to meet the specification, but is sometimes also used for control information. For example, some of the videos shown during menus will have a white rectangle move at integral positions at each multiplicity within this padding area. This white rectangle controls which row in a menu is highlighted during THP playback, for synchronization purposes.

Thwimp can intelligently handle audio, the subvideo array, multiplicity, and padding/control information when encoding THP files to replace the ones in-game. It does this by accepting appropriately named, input MP4 video files for each subvideo cell in the array and for each multiplicity. Where applicable, it will also accept a WAV audio file, and BMP image frames for each multiplicity's padding/control signal as needed. After reading the input files, Thwimp will intelligently process and compose all of the files together appropriately, in order to create a high-quality, properly formatted THP video replacement file.

Main Features

  • Hybrid GUI/CLI application
  • View the hard-coded stat information for each THP file in the original Mario Kart Wii game
  • Playback THP files from the original game
  • Convert THP files into normal video files
    • Rip a particular subvideo/multiplicity within the THP file:
      • Crop video to a particular size relative to a particular position.
      • Clip video to a particular frame range/multiplicity.
      • Rip each unique frame for padding from the multiplicities as BMP image files.
    • Convert video stream in THP file to MP4 (H.264 encoded).
    • Convert audio stream in THP file to WAV file.
  • Encode new, replacement THP files
    • Transform input files into a final THP video:
      • Select individual MP4 input video files for each subvideo cell/multiplicity.
      • Input a WAV input file for sound.
      • Input unique BMP frames for each multiplicity for padding.
    • Adjust the JPG compression quality for frames in the final THP file:
      • Use this to create a balance between quality and bandwidth speed, to prevent stuttering for THP playback on real hardware.
    • Limit each subvideo cell for all multiplicities to an exact frame count:
      • Used to truncate the subvideo length to an exact frame count, if some of the subvideos' length > target limit.
  • Ability to load different Thwimp data filesets
    • Used to allow Thwimp to handle THPs from other games.
    • Detailed documentation on the fileset formats.
  • Ability to save/load settings to/from a settings INI file
  • Progress bars to detail current progress and task being worked on
    • Playback
    • Ripping
    • Encoding
  • Built-in logger for debugging and error-reporting
    • Ability to save log to a file.

Usage

Please read the manual for full usage of the application.

Media

v1.1 Update
v1.0 Release/Tutorial

Version History

Version Date of release Information
v1.0 2018-10-24 First release
v1.1 2019-01-07
  • Fixed THP Encoding framerate bug.
  • Fixed bug with ripping control signal frames from battle_cup_select.thp being off by one multiplicity.
  • Refactored THP Viewer/Ripper UX with the ability to rip individual subvideo cells/multiplicities.
  • Added redirect to this page.
v1.2 2020-08-03
  • Fixed serious, application-breaking bug where pointing to a real i_view32.exe IrfanView executable would cause the THP Encoder process to fail.
  • Optimized THP encoding, especially when handling videos requiring dummy/control padding.
  • Fixed error parsing String datatype into Single datatype when in a foreign culture.
  • Fixed KeepInRange() function parsing bugs.
  • Fixed lingering file I/O from StreamReaders/Writers.
  • Added an additional dummy entry as 0th entry in default Mario Kart Wii data files.
  • Enhanced and improved GUI.
  • Enhanced Thwimp CLI.
  • Enhanced THP Viewer/Ripper.
  • Added new options.
  • Added audio to application.
  • Added progress bars/application logger.
By the same author: MrTamkis

Distributions:
Hover! Pack

Battle Arenas:
Hover! Maze 1Hover! Maze 2Hover! Maze 3Hover! CreditsMTM64 Arena Rumble

Software:
Thwimp