English / Japanese

# MIDITrail Ver.2.0.0 for iOS

Copyright (c) 2010-2022, WADA Masashi All rights reserved.
Web: https://osdn.jp/projects/miditrail/
Mail: yknk@users.osdn.me

## Contents

1. Introduction
2. System requirement
3. How to start
4. Usage
5. Setting
6. Restriction
7. FAQ
8. Appendix
9. Copyright and license
10. History

## 1. Introduction

MIDITrail is a MIDI player which provides 3D visualization of MIDI data sets.
You can enjoy not only listening but also viewing.
MIDITrail supports SMF format 0/1, and multiple MIDI ports.
MIDITrail is available for Windows, macOS and iOS.

Optional feature:
You can enjoy the VR(virtual reality) experience using cheap VR glasses for smartphones and the gamepad for iPhone.

Screenshot: PianoRoll3D
Screenshot: PianoRollRain
VR experience using iPhone

## 2. System requirement

Device: iPad, iPhone, iPod touch
OS: iOS 12.0 or later

When the MIDI data sets contains a great number of notes, MIDITrail needs more performance graphics.

## 3. How to start

### (1) Preparing MIDI files

MIDITrail supports Standard MIDI File (Format0/1).
You have to transfer MIDI files to your iOS device from Mac or PC.
Connect your iOS device to Mac or PC, and launch iTunes. Then you can transfer MIDI files using 'File Sharing'.
Or you can add MIDI files to MIDITrail using Files App of iOS.

### (2) Preparing Sound module

You can use sound module which supports Core MIDI. And you can use internal wavetable synthesizer.
There are three ways as shown below:

The first way is to connect MIDI interface device and external sound module.
(e.g. iRig MIDI, i-MX1, etc.)

The second way is to use Synth App which supports 'Virtual MIDI Port' and 'Background Mode'.
(e.g. KQ Sampei, bs-16i, Sound Canvas for iOS, etc.)

The third way is to use the internal wavetable synthesizer.
You have to transfer the wavetable file (DLS/SF2) to your iOS device in advance.

When you finished preparing sound module, launch MIDITrail and select MIDI OUT device.

## 4. Usage

### (1) Selecting MIDI File

When you select 'MIDI Files' tab, MIDI files stored in your iOS device will be displayed.
You have to transfer MIDI files to your iOS device from Mac or PC in advance by using iTunes's 'File Sharing'.
Or you can add MIDI files to MIDITrail using Files App of iOS.
When you touch a MIDI file, MIDITrail will load the file and open the main screen.
MIDITrail recognizes a file as a text file if its extension is .txt, .doc, or .hed.
You can browse the contents of the file by tapping a text file.

### (2) Main Screen

You can start and stop playback by touching buttons.

[Folder Playback] button
MIDITrail plays the MIDI files in the folder in order of file name.

[Repeat] button
MIDITrail will play MIDI file repeatedly.
When the Folder Playback button is enabled, the first file in the folder will be played when the last file in the folder has finished playing.

[View] button
You can select the following view menu.

Menu | Description
--- | ---
Viewpoint 1 Viewpoint 2 Viewpoint 3 | Move to standard viewpoint.
My Viewpoint 1 My Viewpoint 2 My Viewpoint 3 | Move to my viewpoint.
Save My Viewpoint 1 Save My Viewpoint 2 Save My Viewpoint 3 | Saving my viewpoint.
Switch Rotation Mode | Switch rotation mode of piano roll.
Standard View VR View (Single lens) VR View (Dual lens) | Selecting view style. When you select VR View, the sight direction changes according to the direction of your device.
Lock | Lock the swipe operation and gamepad on the screen.

You can move in space and change the line of sight by operating the directional buttons or swiping the screen.

You can use the gamepad for iOS device to operate.

Button / Stick | Action
--- | ---
Pause button | Play / Pause / Resume
A button | Play / Pause / Resume
B button | Stop
X button | Viewpoint: down
Y button | Viewpoint: up
L1/R1 shoulder button | Change viewpoint
L2/R2 trigger button | Skip back/forward
Directional pad | Viewpoint movement: front and back, right and left
Left thumbstick | Viewpoint movement: front and back, right and left
Right thumbstick | Eye direction

### (3) MIDI IN Monitor

When you select 'MIDI IN Monitor' tab and touch 'Start Monitoring' button, MIDITrail will open the main screen.
You can see data sets received from MIDI IN device in real time on the main screen.
You have to select the MIDI IN device for monitoring in advance.
If you enable the MIDI THRU, MIDITrail will send data sets received from MIDI IN to MIDI OUT while monitoring.
NOTE: MIDITrail can not record data sets received from MIDI IN.

### (4) How to enjoy VR(virtual reality) experience

If you are using iPhone, you can enjoy the VR(virtual reality) experience using cheap VR glasses for smartphones and the gamepad for iPhone.
It is recommended that anti-aliasing is enabled.
1. Connect the gamepad to your iPhone.
2. Start MIDITrail on your iPhone, and select the MIDI file.
3. Tap View button on the main screen, and select "VR View (Dual Lens)" menu.
4. Set your iPhone to the VR glasses, and wear it on your head.
5. Move your viewpoint and start playback by using the gamepad.

## 5. Setting

When select 'Setting' tab, setting items will be displayed.

### (1) View Mode

Select view mode.

### (2) Display Item

Select items which display in main screen.

### (3) MIDI OUT Device

[Port A,B,C,D,E,F]
Select MIDI OUT device.
At least, you must select the MIDI OUT device of "Port A". Ordinary MIDI datasets is sent to "Port A".
If you want to play the MIDI datasets which uses multiple ports, you must select the MIDI OUT device of port B, C, and so on.
To play the MIDI datasets which uses multiple ports, it is necessary to prepare multiple MIDI sound modules.

### (4) Internal Wavetable Synthesizer

[Wavetable File]
If you want to use internal synthesizer, select the wavetable(DLS/SF2) file.
You have to transfer wavetable files to your iOS device from Mac or PC, by using iTunes's 'File Sharing'.
Or you can add wavetable files to MIDITrail using Files App of iOS.
The extension of the wavetable file must be ".dls" or ".sf2".
MIDITrail assigns channel No.10 for percussion.
MIDITrail's internal synthesizer is implemented very simply and has poor performance.
Depending on the wavetable file, the sound may not be output correctly.

### (5) MIDI IN Device

[Port A]
Select MIDI IN device for monitoring.

[MIDI THRU]
MIDITrail will send data sets received from MIDI IN to MIDI OUT while monitoring.

### (6) MIDI File

[Character Encoding]
Select character encoding of MIDI file. This setting will be used when display the title of MIDI file.
This setting is also used when displaying text files on the file list view.

### (7) Playback

[Delay Between Songs]
You can specify the waiting time until the next song starts playback in "Repeat" or "Folder Playback".

### (8) Graphic

[Anti-aliasing]
If anti-aliasing is enabled, a notch (jaggy) will decrease and a more beautiful picture will be displayed.
However, since processing of anti-aliasing is heavy, rendering speed may be poor.
You have to restart MIDITrail to apply this setting.

[Background Image]
If you want to display the background image, select the image file.
You have to transfer image files to your iOS device from Mac or PC, by using iTunes's 'File Sharing'.
Or you can add image files to MIDITrail using Files App of iOS.
The extension of the image file must be ".jpg" or ".png".
The maximum size of the image is 4096 x 4096 pixels.

[Quarter Note Length]
You can change a quarter note length of piano roll. You can specify a value from 0% to 1000%. The default value is 100%.

[Color] (iOS 14 and later)
You can select the color palette and change it to your favorite color scheme. And you can edit color palette too.
* [Set Gradation Colors] You can assign gradation colors for channels that you selected.
* [Set Default Colors] Sets the default color for all items.
* [Export Color Parameters] You can edit the exported parameters with a text editor.
* [Import Color Parameters] You can import the parameters that you edited with a text editor. It is possible to enter part of the parameters.

### (9) Controller

[Gamepad]
You can check the connected gamepad. If you want to start discovering new gamepad, tap this item.

[Touch: Invert X and Y Axis]
This setting inverts the rotation of the X and Y axes for eye direction manipulation by swiping the screen.

## 6. Restriction

### (1) Synchronization of MIDI sound and display

If you use the sound module which delays sound, the sound and display may not synchronize.

### (2) Performance of graphics

MIDITrail renders all notes of the MIDI file in real time.
If the MIDI file has a great number of notes, the load of rendering becomes high.
In order to enjoy the MIDI file which contains tens of thousands of notes comfortably, you have to use iOS device which has high performance graphics.

### (3) Multiple ports

In specification of SMF (Standard MIDI File), a method to select port is not defined.
However there is the unofficial method (*1) to select port. MIDITrail supports that method, but may be unable to play the MIDI file. It depends on the MIDI file.
(*1) Meta event (FF 21 01 pp) is the command to select port.

### (4) Time format of Standard MIDI File

MIDITrail can't open the MIDI file whose delta time represents actual time.

## 7. FAQ

### (1) Q. I want to generate video of MIDITrail. Does MIDITrail have recording function?

MIDITrail does not have a recording function, but you can use Screen Recording button on iOS.
(1) Go to "Settings" -> "Control Center", then tap the Add button (+) next to Screen Recording.
(2) Open "Control Center" on your iPhone/iPad.
(3) Tap the Record button.

    Record the screen on your iPhone, iPad, or iPod touch
    https://support.apple.com/en-us/HT207935

### (2) Q. Can I create playlists?

MIDITrail does not have a plyalists function now, but you can use folder play function.
Please check "(2) Main Screen" in "4. Usage".

## 8. Appendix

### (1) Structure of 3D piano roll visualization

(a) The structure of "Piano roll 3D" visualization

When MIDITrail open the MIDI data sets uses multiple ports, unused port will be not displayed.
For example, if the MIDI data sets uses port A, C and E, MIDITrail displays port A, C and E side by side, and omits port B and D.

(b) The structure of "Piano Roll Rain" visualization

When MIDITrail open the MIDI data sets uses multiple ports, only piano keyboards of port A will be displayed.
However piano roll bars of all ports will be displayed.

### (2) Pitch Bend Motion

The piano roll bar will move with change of pitch bend.
Some MIDI animation works are using pitch bend to shift the piano roll bars without change keys.
If the MIDI animation is not displayed correctly, please disable the 'Pitch Bend Motion' to fix the piano roll bars.

## 9. Copyright and license

WADA Masashi holds the copyright of MIDITrail.
MIDITrail is released under the BSD license.

Copyright (c) 2010-2022, WADA Masashi <yknk@users.osdn.me> All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
* Neither the name of the author nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

## 10. History

yyyy/mm/dd | Version | Changelog
--- | --- | ---
2012/03/17 | Ver.0.0.0 | Development start. It based on the source code of MIDITrail Ver.1.2.0 for Mac OS X.
2012/08/05 | Ver.1.0.0 | First formal release for iOS. #29179 MIDITrail for iOS development.
2014/01/19 | Ver.1.0.1 | #32933 Merged features of MIDITrail Ver.1.2.1 for Mac OS X #32367 Added view mode "Piano Roll Rain 2D" #32427 Added note color assignment to active key #32915 Added support for iPhone5 #32916 Added ability to import files from other apps #32941 Changed Base SDK to iOS6.1 #30548 Fixed bug. (At the start of playback, MIDI data transmission is blocked)
2017/02/12 | Ver.1.1.0 | #35775 Changed URL and mail address in user's manual #36981 Added support for iOS 64bit #36982 Added support for iPhone6, iPhone6 Plus and iPad Pro #36983 Added screen lock feature #36984 Added background image customization #36985 Added support for multiple MIDI OUT ports #36986 Changed launch screen using storyboard #36987 Fixed bug (Japanese locale is not detected)
2017/02/20 | Ver.1.1.1 | #37007 Fixed bug (The numerical value of the counter is incorrect)
2018/01/15 | Ver.1.1.2 | #37881 Added function to delete files and rename files in file list #37882 Added increase of the size of active note #37883 Changed brightness the ripple color #37884 Changed counter string format on iPhone 6 or later #37885 Changed development environment to Xcode 9 #37616 Fixed bug (Piano roll bar flickers in Piano Roll 2D mode) #37860 Fixed bug (Touch screen to call up play menu not working)
2018/02/20 | Ver.1.2.0 | #37955 Added internal wavetable synthesizer #37971 Added function to delete files and rename files in background image file list
2018/09/30 | Ver.1.2.1 | #38649 Added Support for iPhone X,XS,XS Max,XR / iPad Pro 10.5 inch
2019/01/31 | Ver.1.2.2 | #38898 Added VR View mode #38899 Added viewpoint selection menu #38900 Added anti-aliasing support #38901 Added FPS counter #38902 Added support for iPad Pro 2018 (11 inch, 12.9 inch) #38903 Fixed bug (When the iPad is oriented vertically the main screen protrudes) #38904 Changed development environment to Xcode 10
2019/03/31 | Ver.1.2.3 | #39085 Added support for game controller #39086 Changed the check mark to switch control on setting screen #39087 Changed the camera up vector setting on VR view
2019/05/05 | Ver.1.2.4 | #39213 Added quarter note length configuration #39214 Fixed bug (VR View is not stereoscopic on iPhone X series) #39215 Fixed bug (memory leak of background image processing) #39216 Changed section content of setting view #39217 Changed development environment to Xcode 10.2
2019/11/30 | Ver.1.3.1 | #39796 Added view mode "Piano Roll Ring" #39797 Added file search bar #39798 Added support for "Files" app #39799 Added support for background playback #39800 Added support for dark mode #39808 Added auto rotation feature #39801 Changed development environment to Xcode 11 #39802 Changed game controller support implementation #39803 Changed UIWebView to WKWebView #39804 Changed mark of "Quarter Note Length" cell in setting view #39805 Changed MIDI device identification rule #39806 Fixed bug (Code analysis found some mistakes) #39807 Fixed bug (Error dialog must be displayed by main thread)
2020/04/15 | Ver.1.3.2 | #40322 Added support for folder selection in file list view #40325 Added displaying file name in main view #40323 Fixed bug (MIDITrail crashes when displaying help view on iOS 9)
2021/04/12 | Ver.1.3.3 | #41978 Added support for iOS 14 (Core MIDI new API) #41979 Added support for iPhone 12 series, iPad(7th,8th) and iPad Air(4th) #41980 Added folder playback feature #41981 Added playback information display on lock screen #41982 Added remote control feature #41983 Added creating folder feature and moving file feature on file list view #41984 Added moving file feature on background image selection view #41985 Added searching for background image files in sub folders #41986 Added moving file feature on wavetable file selection view #41987 Added searching for wavetable files in sub folders #41988 Changed development environment to Xcode 12 #41989 Fixed bug (UI API called from background thread)
2021/06/01 | Ver.1.3.4 | #42423 Added file import button in file list view #42424 Added support for Standard MIDI File with illegal chunk size #42425 Added support for RIFF-based MIDI File #42426 Added sending "All Sound Off" message when pause/stop/skip
2021/09/07 | Ver.1.3.5 | #42794 Added setting of delay between songs #42795 Fixed bug (Sending System Exclusive causes crash when data size is zero) #42797 Fixed bug (When the action sheet or help view is displayed, the app crashes at the end of song in Folder Playback mode)
2022/07/31 | Ver.1.3.6 | #45282 Added screen gamepad #45283 Added feature of saving my viewpoint #45284 Added display switch of grid line and time indicator #45285 Added 2nd light for Piano Roll 3D #45286 Added support for iOS 9.0 or later #45287 Added support for iPad mini(6th) #45288 Added MIDI system message parsing #45289 Changed view action sheet to popover view #45290 Changed alert display processing #45291 Changed development environment to Xcode 13 #45292 Fixed bug (display item switch flickers on setting view)
2022/12/11 | Ver.2.0.0 | #46245 Added feature of color configuration #46246 Added bar ring for Piano Roll Ring #46247 Added function to send note off when paused or stopped and note on when resumed #46248 Added support for iPhone 14 Pro, 14 Pro Max #46249 Added text file viewer #46250 Changed key color of Piano Roll Rain #46251 Changed development environment to Xcode 14 #46252 Changed graphics API from OpenGL to Metal #46253 Changed button design #46254 Changed app name animation in startup screen #46255 Fixed bug (MIDITrail is not reading tempo data correctly) #46256 Fixed bug (The folder button disappears when searching is canceled) #46257 Fixed bug (MIDITrail crashes when connecting/disconnecting game controller)