updated documentation and installation instructions

Author: jschaul

LICENSE.md

@@ -1,55 +1,85 @@
-README for KommHELP Talkshow
+# README for KommHELP Talkshow
 
 Talkshow is a hierarchical sound board application for portable touch screen computers. It is meant to help non-speaking people.
 
-Talkshow is based on python and the pyglet library. It runs on Windows, OS X and Linux (not tested yet)
-
-MOTIVATION
+## MOTIVATION
 
 Non-speaking people depend on special devices to communicate with the people that surround them. There are devices on the market that play pre-recorded sound samples by pressing a button and allow the user to change sample sets according to context. However, these special device are ridiculously expensive.
 
 With Talkshow, we try to provide a solution based solely on Open Source software that runs on a cheap Netbook with a touch screen.
 
-LICENCE
+## LICENCE
+
+Talkshow open source software licensed under the terms of the GPLv3, which guarantees end users (individuals, organizations, companies) the freedoms to use, study, share (copy), and modify the software. If you make changes to the code however, you need to make the source code of these changes available to the public.
+
+## INSTALLATION
+
+### Installation instructions when downloading windows exe:
 
-Talkshow is licensed under the terms of the GPL. This means you can use it for whatever purpose you like. If you make changes to the code however, you need to make these changes available to the public.
+* Download the talkshow.exe file
+* Download and install the VLC media player from [this direct link](https://get.videolan.org/vlc/2.1.3/win32/vlc-2.1.3-win32.exe) or choose another version from [https://www.videolan.org/](https://www.videolan.org/). Please make sure it's 32 bit.
+* Create a folder called "content" next to the talkshow.exe file, and fill it with subfolders containing media files and optionally png images (see [usage instructions](#usage).
 
-INSTALLATION
+You should now be able to use run talkshow. In case of problems, please send me ([email protected]) the debug.log file that was created next to the talkshow.exe file.
 
-You need to install a python interpreter for your platform (ActivePython for Windows for example) and the pyglet library, and the tinyCSS library.
-I suggest Python version 2.7.XX for now, this module has not been tested on Python 3 and may fail.
-Pyglet can be found here: http://www.pyglet.org/download.html
-TinyCSS can be found here: http://pythonhosted.org/tinycss/ or here: https://pypi.python.org/pypi/tinycss
-After you have installed these components, simply put the files that make up Talkshow into a new directory, open a command line and type:
-<path-to-python-interpreter>/python talkshow.py
+### Advanced: install from source
 
-On windows, this might look like this:
+Please see [installation from source](doc/INSTALLATION_FROM_PYHON_SOURCE) if you want to run the python source version of KommHELP talkshow or if you want to make changes to the code.
 
-c:\Python27\python talkshow.py
- 
-USGAE / CREATING CONTENT
+## USAGE / CREATING CONTENT [usage]
 
 The user interface consists of colored rectangles that either play a sound or contain more colored rectangles.
-All rectangles have a caption and optionally may have an associated icon.
-You create this hierarchy of rectangles by creating a hierarchy of subdirectories in the content directory, one subdirectory per rectangle. Each subdirectory may contain more subdirectories or a sound file in wav format and an image in png format that will be used as the rectangle's icon. The sound file will be played once the rectangle is touched in the UI. The name of the directory will be used as the caption of the rectangle.
+All rectangles have a caption and optionally may have an associated icon (.png).
+You create this hierarchy of rectangles by creating a hierarchy of subdirectories in the content directory, one subdirectory per rectangle. Each subdirectory may contain more subdirectories or a sound file (see [supported formats](#formats) and an image that will be used as the rectangle's icon. The sound file will be played once the rectangle is touched in the User Interface. The name of the directory will be used as the caption of the rectangle if there is no image.
+
 See the provided content directory structure as an example.
 
-If you create sample sets this way, please make them available to the public. I would be happy to hear about it. (my email address is at the end of this file)
+If you create sample sets this way, please make them available to the public. I would be happy to hear about it, please contact [http://kommhelp.de/](http://kommhelp.de/index.php/impressum-kontakt-top) [email protected]
 
 The buttons to the left have the following meaning: 1) Play an alarm signal, 2) go to upper directory ("content"), 3) go back one level, 4) quit the program.
 The buttons to the right allow you to set the volume of the program (it's the program's internal volume, not your computer master volume)
 
-TROUBLESHOOTING
+## TROUBLESHOOTING
+
+A log file called `debug.log` and `warn.log` is created in the folder of the executable: any errors occurring will be logged there. In case of issues, send us an email and attach both files, so it's easier for us to find out what the problem is.
+
+## Technical details
+
+KommHELP Talkshow has been written in Python and requires :
+
+* Python pyglet library (bundled with the .exe file, BSD licensed)
+* Python tinycss library (bundled with the .exe file, BSD licensed)
+* VLC media player (more precisely the libvlc part of VLC. VLC needs to be installed separately, GPL licensed)
+
+It has been tested on Windows and linux, but should also work on Mac OS (not tested yet). It is based on 32bit Python 2.7 with the VLC 32 bit version. If both VLC and your version of Python are 64 bit, it can also work without further changes.
+
+See [installation from source](doc/INSTALLATION_FROM_PYHON_SOURCE) for more details on dependencies. 
+
+## BACKGROUND
+
+KommHELP is a non-profit association based in Berlin, Germany that develops hardware and software solutions for people with special communication needs. More information (in German) can be found here: [http://kommhelp.de/](http://kommhelp.de/)
+
+### Developers:
+
+* November, 7th 2009 -- Jan Bölsche <[email protected]>
+* ...?
+* February 2013 - February 2014 -- Joé Schaul <[email protected]>
+
+
+
+
+
+
+
+
+
+
+
+
+
 
-If you encounter an error message like this:
-"TypeError: unsupported operand type(s) for -: 'NoneType' and 'float'", read about it here http://overooped.com/post/93720695/deathtroid-crash 
-A log file called warn.log is created in the folder of the executable: any errors occurring will be logged there. In case of issues, send me (Joé) an email and attach the warn.log file, so it's easier for me to figure out what the problem is.
 
-BACKGROUND
 
-KommHELP is a non-profit association based in Berlin, Germany that develops hardware and software solutions for people with special communication needs. More information (in German) can be found here: http://kommhelp.de/
 
 
--- November, 7th 2009 -- Jan Bölsche <[email protected]>
 
--- 23rd June 2013 -- Joé Schaul <joe.schaul     gmail.com  (replace the spaces with an @)>

README.md

@@ -0,0 +1,96 @@
+
+## Installation instructions from python source under Windows
+
+This section is meant for developers or people who wish to change the functionality of the KommHELP talkshow application. A normal user should not need to read this section, please refer instead to the [INSTALLATION](../README.md#INSTALLATION) section.
+
+See [other operating systems](#other) if you're not on Windows.
+
+### Step 1: Install Python
+
+* Download python 2.7.6 for 32 bit from [http://www.python.org/download](http://www.python.org/download)
+it is important that the python version is at least 2.7, but not version 3.something. It is also important that the python version is for 32 bit systems, even if you have a 64 bit computer. So for Windows it's [Python 2.7.6 Windows Installer](http://www.python.org/ftp/python/2.7.6/python-2.7.6.msi)
+* Install Python to a place you can find, for example `C:\Python27_32bit` Ideally the path should contain no spaces as that could create problems.
+
+For the rest of this document I will assume you installed python to `C:\Python27_32bit`. If that is not the case, please adapt the paths below to match you installation path.
+
+
+### Step 2: Install "pip" package manager, and with pip install the python dependencies "tinycss" and "pyglet" [pip]
+
+* download PIP for windows: [https://sites.google.com/site/pydatalog/python/pip-for-windows](https://sites.google.com/site/pydatalog/python/pip-for-windows)
+* open the downloaded file, it might open a few command line windows and ask you to press a key - just press enter and wait for it to download what's necessary. Point it to your python executable (for example `C:\Python27_32bit\python.exe`):
+![pip1](pip-win1.png)
+Next, enter `pip install tinycss pyglet` into the second text field, and press `Run`:
+![pip1](pip-win2.png)
+
+### Step 3: Configure python on your system
+
+Open a command line and enter: `python`
+You should get something like this:
+
+```
+Python 2.7.6 (default, Nov 10 2013, 19:24:18) [MSC v.1500 32 bit (Intel)] on win32
+Type "help", "copyright", "credits" or "license" for more information.
+```
+
+type `exit()` to get out of the Python shell.
+
+#### if the above does not work or if you get the wrong python version:
+
+The python is not available on your system path and you need to add it. Open system environment variables, find the entry for "Path" and add the directory of your python installation, and the `Scripts` subfolder to the beginning, separated by `;` and followed by a `;` sign:
+
+```
+C:\Python27_32bit;C:\Python27_32bit\Scripts;someotherpaths
+```
+
+If you get the wrong python version, change the Path variable so that it points to the correct installation directory instead. Please be careful during this step and ensure all paths are correctly separated with a `;` symbol.
+After you added system variables, close your command line, and re-open it again (so it refreshes the Path variable)
+
+### Step 4: Download and install VLC
+
+Get VLC from [this direct link](https://get.videolan.org/vlc/2.1.3/win32/vlc-2.1.3-win32.exe) or choose another version from [https://www.videolan.org/](https://www.videolan.org/). Please make sure it's 32 bit.
+
+### Step 5: Confirm you can start talkshow
+
+Double-click on the talkshow.py file, or, if that does not work, from a terminal, enter:
+
+```
+python path_to_talkshow_folder\talkshow.py
+```
+or
+```
+C:\Python27_32bit\python.exe path_to_talkshow_folder\talkshow.py
+```
+
+### How to distribute kommHelp talkshow as a windows binary: Compile python sources to .exe executable
+
+Download and install **pywin32** from this [direct link](http://sourceforge.net/projects/pywin32/files/pywin32/Build%20218/pywin32-218.win32-py2.7.exe/download) (if it does not work, find the version you need from here: [http://sourceforge.net/projects/pywin32/files/](http://sourceforge.net/projects/pywin32/files/)
+
+Install **pyinstaller** with pip: `pip install pyinstaller` (see [Step 2 for how to get pip on Windows](#pip)).
+
+Check that `pyinstaller` on the command line works. If not, you need to add `C:\Python27_32bit\Scripts` to your environment variables.
+
+Change directory to the folder containing the talkshow.py file: `cd your\path\to\the\directory\with\talkshow`
+Then execute the pyinstaller command with the following arguments:
+
+```
+pyinstaller talkshow_noVLC.spec --clean -noconfirm --noconsole --onefile
+```
+
+if you have the libvlc.dll, libvlccore.dll and the vlc plugins directory in the same directory than the talkshow.py file you can also use the talkshow_full.spec file to include VLC in the windows binary.
+
+This will generate a `talkshow.exe` file under `dist\talkshow` containing all the needed dependencies that you can distribute. You need to provide your own `content` folder alongside. 
+
+
+### Other Operating Systems [other]
+
+If you have Python 2.7, download [pip](http://www.pip-installer.org/en/latest/installing.html) and then do
+
+```
+pip install pyglet tinycss pyinstaller
+```
+
+if you have another version of python, install 32 bit Python 2.7, and then get Virtualenv from [here](http://www.verious.com/code/CharleneJiang/virtualenv-burrito/), and use it to make a python virtual environment for this version of python. Then, once in that shell, execute the above pip command (virtualenv comes bundled with pip).
+
+Then you need to install [VLC](https://www.videolan.org/vlc/) if you don't have it already. Please see the sections above for more details on dependencies. 
+
+

doc/INSTALLATION_FROM_PYTHON_SOURCE.md

@@ -31,11 +31,6 @@
 except:
     logger.error("There is a problem with VLC. Either you are using the wrong version of talkshow (32/64 bit), or there is a bug in the code, or you can try and install VLC.")
 
-try:
-    os.path.isdir
-except:
-    logger.error("There is a problem with VLC. Either you are using the wrong version of talkshow (32/64 bit), or there is a bug in the code, or you can try and install VLC.")
-
 
 try:
     import CommandBar

doc/pip-win1.png

@@ -0,0 +1,63 @@
+# -*- mode: python -*-
+a = Analysis(['talkshow.py'],
+             pathex=['.'],
+             hiddenimports=[],
+             hookspath=None,
+             runtime_hooks=None)
+
+
+def Datafiles(*filenames, **kw):
+    import os
+
+    def datafile(path, strip_path=True):
+        parts = path.split('/')
+        path = name = os.path.join(*parts)
+        if strip_path:
+            name = os.path.basename(path)
+        return name, path, 'DATA'
+
+    strip_path = kw.get('strip_path', True)
+    return TOC(
+        datafile(filename, strip_path=strip_path)
+        for filename in filenames
+        if os.path.isfile(filename))
+
+
+data_list = []
+for dirname, dirnames, filenames in os.walk('style'):
+    for filename in filenames:
+        data_list.append(os.path.join(dirname, filename))
+style = Datafiles(*data_list, strip_path=False)
+
+
+data_list = []
+for dirname, dirnames, filenames in os.walk('alarm'):
+    for filename in filenames:
+        data_list.append(os.path.join(dirname, filename))
+alarm = Datafiles(*data_list, strip_path=False)
+
+
+# add static files
+other_data_files = Datafiles('README.md')
+
+
+
+pyz = PYZ(a.pure)
+exe = EXE(pyz,
+          a.scripts,
+          exclude_binaries=True,
+          name='talkshow.exe',
+          debug=False,
+          strip=None,
+          upx=True,
+          console=True )
+coll = COLLECT(exe,
+               a.binaries,
+               a.zipfiles,
+               a.datas,
+               style,
+               alarm,
+               other_data_files,
+               strip=None,
+               upx=True,
+               name='talkshow')