Trying to understand the file format of Tip Toi
Haskell C Perl HTML Shell Makefile
Latest commit 6bda152 Feb 10, 2017 @nomeata nomeata README: Do not mention matlab scripts
They were removed in c75b12a
Permalink
Failed to load latest commit information.
Audio Remove tttool create-debug and create Debug.yaml instead Jan 28, 2015
docs added svg files with real codes for use with e.g. inkscape Sep 9, 2014
example Assemble and export the initial play list Jan 25, 2014
perl-tools -notext eingefügt um die codes ohne text zu drucken Feb 17, 2015
playmus playmus: Do not fade in, do not delay exiting. Apr 25, 2015
scripts Add files downloaded by scripts/update.sh to .gitignore Jun 20, 2016
src Implement reading and setting the language header field Dec 6, 2016
templates Update Spielfiguren3.yaml Dec 1, 2016
transcript Fixed some typos Feb 9, 2014
wip Update Hardware.md Feb 5, 2015
.gitignore Add a cabal file Jan 18, 2015
.travis-setup-linux.sh .travis.yaml: Enable stack Jun 7, 2016
.travis-setup-windows.sh .travis.yaml: Enable stack Jun 7, 2016
.travis.yml travis typo Jun 7, 2016
Changelog.md Implement reading and setting the language header field Dec 6, 2016
Debug.yaml Remove tttool create-debug and create Debug.yaml instead Jan 28, 2015
GME-Format.md Mention `gme-lang:` in `GME-Format.md` Dec 6, 2016
LICENSE Improve .cabal file and add travis integration. Jan 19, 2015
Makefile Update steps for building tttool Feb 1, 2015
README.md README: Do not mention matlab scripts Feb 10, 2017
Setup.hs Improve .cabal file and add travis integration. Jan 19, 2015
example.yaml Update example.yaml Jan 31, 2015
gameanalyse.c Fix warnings in libtiptoi.c and gameanalyse.c when compiling with gcc… Jun 20, 2016
gen-windows-release.sh Avoid incomplete pattern Jan 31, 2016
generate-oid-table.sh Add oid-table.png and the script that created it Jan 28, 2015
libtiptoi.c Fix warnings in libtiptoi.c and gameanalyse.c when compiling with gcc… Jun 20, 2016
makegraphic.c Comment makegraphic.c Nov 30, 2014
oid-decoder.html Cleanup and file reorganisation Jan 26, 2014
oid-table.png Add oid-table.png and the script that created it Jan 28, 2015
text2speech-multi-lang.yaml Add multi language text to speech mode. Feb 15, 2015
text2speech.yaml Add multi language text to speech mode. Feb 15, 2015
tttool.cabal Bump directory, vector, time Jan 8, 2017

README.md

Das tttool hat jetzt eine deutsche Webseite für Anwender: http://tttool.entropia.de/

tip-toi-reveng

The goal of this project is to understand the file and paper format for the Ravensburger TipToi pen. The ultimate goal is that everyone can create their own books, with their own sounds.

The current status is that we understood most of the file format (see the GME file format specification). We provide a tool that allows you to dissect these files.

The tool can also be used to generate completely new files from scratch; see below for details.

If you want to learn more please have a look into our wiki (https://github.com/entropia/tip-toi-reveng/wiki).

The tttool tool

Use the tool tttool to investigate the gme files and build new ones. It supports various subcommands:

GME creation commands:
assemble                 creates a gme file from the given source

OID code creation commands:

oid-table                creates a PDF file with all codes in the yaml file
oid-codes                creates PNG files for every OID in the yaml file.
oid-code                 creates PNG files for each given code(s)

GME analysis commands:
info                     Print general information about a GME file
export                   dumps the file in the human-readable yaml format
scripts                  prints the decoded scripts for each OID
script                   prints the decoded scripts for a specific OID
games                    prints the decoded games
lint                     checks for errors in the file or in this program
segments                 lists all known parts of the file, with description.
segment                  prints the decoded scripts for a specific OID
explain                  print a hexdump of a GME file with descriptions
holes                    lists all unknown parts of the file.
rewrite                  parses the file and writes it again (for debugging)

GME extraction commands:
media                    dumps all audio samples
binaries                 dumps all binaries

Simulation commands:
play                     interactively play a GME file

Run

./tttool --help

to learn about global options (e.g. DPI settings), and

./tttool command --help

for the options of the individual command.

Installation

This program is written in Haskell and can be installed on Windows, MacOS or Linux.

For Windows users, we create zipfile containing tttool, you can find them in the releases section of the github project.

Otherwise, installation from source is not difficult either:

  1. If you have not done so yet, fetch the source code and change to the directory containing the code:

    git clone https://github.com/entropia/tip-toi-reveng.git tttool
    cd tttool
    
  2. Install the Haskell platform, see http://www.haskell.org/platform/ for details for your system. Users of Debian or Ubuntu simply run

    apt-get install haskell-platform
    
  3. Install the development packages for ncurses, i.e.

    apt-get install libncurses5-dev
    
  4. Install the Haskell dependencies. The Haskell platform comes with a tool called cabal, and you should run the two commands

    cabal update
    cabal install --only-dependencies
    
  5. Now you can build the program using

    cabal install --bindir=.
    
  6. At this point, tttool should be ready to go. If you run

    ./tttool
    

    you should see the list of commands shown above.

If you have any problems, you can report an issue via GitHub.

Building your own gme files

Once you have installed tttool, you can create your own .gme files. The process is as follows

  1. Record the audio samples you want to include, as Ogg Vorbis files, mono, 22050Hz. I use

    arecord -r 22050 foo.wav
    oggenc foo.wav
    rm foo.wav
    
  2. Write a my-book.yaml file containing some general information, and especially the scripts (i.e. what to do) for each OIDs (i.e. the various fields of a book). You can use the example.yaml file as a starting point; it contains more information in its comments.

  3. Run ./tttool assemble my-book.yaml, and make sure it reports no error, i.e. finishes silently.

  4. Copy the now generated my-book.gme to your TipToi pen and enjoy!

If you need to find out what OID code corresponds to what part of the book, you can generate a debug gme using the debug.yaml file, adjusting its Product-Id to your product’s id, building it with ./tttool assemble debug.yaml and loading the resulting debug.gme on your pen. It will then read out the codes, as a sequence of english digits.

If you want to convert existing audio files of almost any format, and you have ffmpeg installed, you can use

ffmpeg -i input-audio-in-some.fmt -ar 22050 -ac 1 foo.ogg

Text to speech

If you have libttspico-utils and vorbis-tools installed, you can have tttool generate audio files from text for you, which makes developing your yaml file much easier. See text2speech.yaml for more information.

Printing your own books

With the code in this repository, you can create GME files. This is even more fun if you can also create your own books! „Pronwan“ found out how that works, as you can see in this video demonstration. He also published 30 minute video tutorial (in German).

Press Review

TODO

  • What are all the header fields? (See wip/Header.md)
  • Finish decoding the games. (See wip/games.txt)
  • What is the purpose of the additional script table?

Other resources in this repository

  • oid-decoder.html allows you to manually decode an OID image.
  • scripts/update.sh downloads all gme files from the Ravensburger server (requires perl and the XML::Simple module).

    Instead of downloading all of them, you can conveniently browse them at http://tiptoi.vakat.de/, a service provided by Falko Oldenburg tiptoi@vakat.de.

  • gameanalyse.c and libtiptoi.c is an alternative tool to investigate gme files. It can also replace audio files in gme files; compile and run it for diagnostic output.
  • Audio/ contains some audio files, such as digits read out.
  • docs/ collects information about TipToi found elsewhere.
  • wip/ (work in progess) contains notes about the parts of the gme files that are not fully understood yet.
  • perl-tools contains a perl based script, to generate a PDF with all OID codes from a yaml-file as well some functions to generate PNG-files, inject pHYs-chunks with resolution hints into GD generated PNG files as result from some testing