- TI-Vibe v0.1 for TI-89/TI-89 Titanium/TI-92+/Voyage 200 -
I. What is TI-Vibe?
TI-Vibe is a music player for TI-68k calculators. It outputs to the
I/O port what will probably be the best sound you will be able to hear
on these 12Mhz devices (7 bits, mono, ~22khz).
II. Using TI-Vibe
First you need to convert the audio file you want to play to a TI
file. A script is provided for an automated conversion on Windows: it
is based on the MP3 encoder LAME, the sampling rate converter SSRC,
and a custom Python script vibegen.py. You don't need to download
anything except Python, everything is provided in TI-Vibe's package.
* Download and install Python: http://www.python.org/download/
* In Windows's System Properties, add the path to Python's
installation directory to the PATH environment variable.
* Copy the .wav or .mp3 file you want to convert to the bin/ directory
of TI-Vibe's distribution. Don't choose a file too big that won't
fit in the calculator's memory once converted: ~22130 bytes
(depending on the SAMPLE_RATE chosen, see further) are needed on the
calculator per second of music. For example on TI-89 Titanium and
Xpanded Voyage 200 with their ~2.5MB of free archive memory, you can
fill all the memory with a ~117-second long song.
* You may set a few parameters for the conversion. Edit vibegen.bat in
the bin/ directory and change the default value of these variables
at the beginning of the script:
- SAMPLE_RATE: it has been configured to 22200 for a Titanium HW3. For
HW1 models it should be lower, for a TI-92 Plus HW2 it should be
higher. The correct value depends on the frequency of the CPU and
on how fast the Flash memory chip is. You have to make a few tests
to find the value which makes TI-Vibe play the file at a good
tempo on your calculator.
Also SSRC (the sampling rate converter) sometimes returns errors
depending on the input file sampling rate (followed by Vibegen
reporting 'not a WAVE file'): slightly changing SAMPLE_RATE is in
this case needed.
- SCALE: the sound will probably be too low when played by TI-Vibe,
the original file needs to be scaled. 3 is a good value, but you
may write a higher one here if it is still played to low.
* Open an command line console, 'cd' to the bin/ directory, and run
the conversion: vibegen.bat infile[.mp3/.wav] tiname
A TI group file is created ([tiname.89g], containing the wave data
splitted in archived variables gathered in the folder you have
chosen ('tiname'). If it isn't, a tool in the chain (scaling, mp3
decoding, sampling rate conversion, conversion to a TI file) has
probably failed, read the error report for more details on at went
wrong.
* Send tivibe.89z and the group file to the calculator. They are
TI-89 files, but may be sent to any TI-68k model. Depending on how
much archive memory is left, you will perhaps not be able to send
all the variables in the group file. Don't worry, TI-Vibe will still
work. Caution, you may sometimes see the calculator asking for a
garbage collection, just confirm, wait a few seconds, and continue
the transfer.
* Plug a 2.5mm to 3.5mm jack adapter into the I/O port and let the fun
flood into your headphones by running:
tivibe('tiname') - where 'tiname' 6is the name chosen during the
conversion (the name of the folder). You can press any key to stop
TI-Vibe.
III. What about Linux/Mac OS/[Insert favorite OS here]?
LAME and SSRC can be built for many Operating Systems (see the links
further), the Python script Vibegen can be run on all the OS supported
by Python, and the batch file Vibegen.bat can easily be adapted to
your needs.
IV. How does TI-Vibe work?
Pulse Width Modulation is used: a square wave is generated for each
sample, whose width depends on the sample's value. For a n-bit signal,
we have to be able to create 2^n different types of squares, with a
sampling rate as high as possible. The precision achieved depends on
the frequency of the CPU and on the number of cycles required for a
waiting instruction (NOP).
With a 12Mhz CPU and 2-cycle long NOPs (taking into account the cycles
needed for keyboard and input data reading), a 7-bit signal at 22khz
is a good compromise (with high frequency statics due to PWM, but
fortunately not too annoying).
100% of CPU time is used, don't expect to be able to use this method
for background playing in games.
V. Licenses
* Naoki Shibata's sampling rate converter SSRC
(http://shibatch.sourceforge.net/) and the MP3 encoder LAME
(http://lame.sourceforge.net/) are distributed under the GNU LESSER
GENERAL PUBLIC LICENSE. See LGPL.txt for details.
* TI-Vibe (the TI program and the scripts vibegen.bat and vibegen.py)
are distributed under a BSD-like License:
- TI-Vibe for TI-89/92+/V200/Titanium -
Copyright (C) 2006 Olivier Armand - All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. 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.
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 FOUNDATION 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.
VI. Contacting the author
Ask your questions and send bug reports and suggestions to:
Olivier Armand (aka ExtendeD) - <olivier d0t calc at gmail d0t com>
Please read the whole documentation before sending any e-mail.
If you find TI-Vibe useful (Er.. can TI-Vibe be useful?), or if you
want to help me continue my work on TI-68k platforms, please consider
making a donation via PayPal, even a very small one, to the e-mail
address above.
VII. History
2005-04-15: v0.1
* First public release.
2006-04-02:
* The player and the conversion scripts works.. but my Titanium is
10 times the size of my MP3 player. Mmm, perhaps I've lost again
my time. Give me 13 more days to write the documentation (a good
line-rate of 10 lines/day for my 12Mhz brain).
2006-03-24:
* First lines of code for the project.
VIII. Thanks to:
* James Montelongo for sharing details on Real Sound for TI84+
for his help with TI-Vibe.
* Romain Liévin and Tim Singer for the documentation on TI file
formats of their TI Link Protocol Guide.
* Jon Holbrook, for being an Holbrook, for his successful leak in
the top right-hand corner of the Universe, and for his help in
writing an indecent ReadMe file.