gSUB - Subtitle application for Dreambox
========================================

Author: Gruffy
Contact: gruffypuffy1234 AT hotmail DOT com


What is gSUB?
-------------
This is a subtitle application for the Dreambox Set-Top-Boxes by Dream Multimedia TV Gmbh. It should be installed
onto your box and put into an "init" script so that it automatically starts when you start the box. Then, when you
select a channel with Teletext or DVB subtitles it will automatically start to show these.

System Requirements
-------------------
 - Enigma based firmware in the Dreambox. Should work with any Dreambox model but the author is using a DM500T for 
   development, and this is hence the only box it is tested on.
 - A Busybox with the "wget" command available. gSUB is using the WebIF to get some information from the Enigma and at the
   time of this release it was using the "wget" internally. This is up for change and this requirement will be removed in
   some future releases...maybe :-) Check in your /bin directory for a symlink "wget" to Busybox.
 - NOTE! IT WILL NOT WORK ON NEUTRINO BASED IMAGES! This is because gSUB is using the Enigma web interface (WebIF) to get
   information from the Enigma application.
 - It will NOT work on MIPS based Dreamboxes such as the DM7025.
 - This release will try and use the /tmp/pmt.tmp to get zapping faster an non-dependant on WebIF. 
   If you have an image without this (PLi Flabber for example) gSUB will fallback to using the WebIF,
   and in this case, the WebIF is required.

Features includes...
--------------------
 - Using TrueType fonts for displaying, using one color with outline. (White text, black outline is default.)
 - Detecting if playing a recorded file and in this case a "delay" is added to get the subtitles into sync. (The time of 
   this delay is controlled through the gSUB.conf file.)
 - Avoid to display subtitles if any Enigma window is detected.
 - Selectable language, tested with Swedish, Norwegian, Danish, Finish and English. Implemented German, Dutch, Italian, 
   French and Spanish but not tested as the developer is based in Sweden. However tested by others!
 - Selectable position of text to allow for 16:9 or 4:3 TV sets.
 - Support for different settings for 4:3 or 16:9 transmissions.
 - Selectable size of font.
 - Use background (black blob behind text) or not.
 - Center/Left adjustment of text.
 - Basic settings accessed through Enigma plugin.
 - Advanced settings are controllable through a file, gSUB.conf.
 - Automatic suspend/kill during recording to conserve CPU power.
 - Hardcoded channels in file gSUB.channels so that the user can show gSUB what language
   it shall use when translating chars.
 - Support for audio pid /audio channel selection through gSUB.audio
 - Autostart enable/disable through GUI.
 - NEW: DVB Subtiles included!!!
 - Only using WebIF for Audio changes, a lot less spam on Enigma...
 

Install
-------
Install the files into the following structure:
var/bin/gSUB				<- Exefile for DAEMON (must be installed here!!!)
var/bin/2SUB				<- Exefile for APPLICATION (must be installed here!!!)
var/etc/init				<- init script that is starting gSUB
                               These lines of code could be moved into other start scripts
							   for example the ones used in 7020 images /etc/init.d/bootmisc.sh
var/tuxbox/config/gSUB/gSUB.conf	 <- config file for gSUB
var/tuxbox/config/gSUB/gSUB.channels <- config file for channels
var/tuxbox/config/gSUB/gSUB.audio    <- config file for audio settings
var/tuxbox/plugins/gSUBConf.so		<- The gSUB Configurator plugin
var/tuxbox/plugins/gSUBConf.cfg

NOTE! The included "init"-file is only containing the start of gSUB. If you have something else in your setup you should
merge the lines for starting gSUB into your "init" script. See "Advanced info about autostart" below.

Also, make sure that the font pointed to by the gSUB.conf is existing on your system. If you would like to use your own font,
simply point to it with the gSUB.conf and restart gSUB. Make sure it contains the characters for your language!

Language: The gSUB is implementing "translations" of special chars for different languages. This is done for the languages
defined above. Note that it is possible to select a non existing language in the conf file. If this is a correct language
code in the Teletext standard it should come up, but special characters are not shown. If you want this inside gSUB, make 
notes about the displayed characters and what you were expecting and send it to the author. Maybe it will make it into the 
next version of gSUB!
Supported & Tested languages: Swedish, Danish, Finnish, Norwegian, French, German, Dutch, Spanish, Italian and English.

Important: If you have changed your WebIF login/password/port you must edit these things in the gSUB.conf file. This 
could be done with a UNIX editor or from the gSUB Configurator GUI.


Advanced info about autostart
-----------------------------
When gSUB is started from an init script, it should be started with something like:
/var/bin/gSUB &
This will start a gSUB daemon that is then used by the plugin to spawn new instances of the gSUB subtitle application. 
To manually start a subtitle application without the daemon use "gSUB -nodaemon" from the command line prompt.
Below you can see how this is done in the "init" file.
----------- CUT FROM "init" ------------
if [ -x /var/bin/gSUB ]; then 
	/var/bin/gSUB&
fi
----------- END CUT FROM "init" --------

N O T E ! ! !
=============
THIS IS DIFFERENT ON ALL IMAGES USED! CHECK THE DETAILS OF YOUR IMAGE OR ASK ON THE FORUMS FOR A REPACKED 
VERSION OF GSUB FOR YOUR IMAGE! IF YOU INSTALL WRONG PACKAGE YOU MIGHT END UP WITH A FAULTY IMAGE AS THE
GSUB PACKAGE MAY HAVE INSTALLED ITS INIT/BOOT FILE OVER YOUR IMAGE FILE!


Search modes for external files gSUB.channels and gSUB.audio
============================================================
To make sure that almost everything is possinbe with gSUB in terms of finding channels that are not announced
in the transport stream so that gSUB can find them a set of external files can be used. (See details about these
files below.) But, there is also a set of configurations one can set to make these files work in a different mode.

Language mode:
---------------
This mode will only use settings from the gSUB.XXXX files if correct language is set. It means that if will only
find subtitle settings and audio settings from one of your languages set in the gSUB.conf file. 
Settings for this to work is:
UseExternalChannels 2 or 1   <-- set in override or fallback, depending if you like to search gSUB.channels
                                 before or after gSUB is searching the transport stream, 0 - disable.
UseExternalAudio 1           <-- Must be enabled to have effect at all, 0 - disable.
ExternalSearchMode 0         <-- This is the "mode"... 0 = Language and ServiceID must match to find setting.
                                 It is valid in both gSUB.audio and gSUB.channels.
                                 
Service ID mode:                                 
----------------
Use this to have the external files to be searched without a forced match for language setting. I.e. this means
that you can have "Swedish" and "English" set as languages but the gSUB app will be able to generate subtitles
in other languages by using the hardcoded service ID in the gSUB.channels. (This is true for gSUB.audio as well).
Note that in this mode...gSUB will use the FIRST Service ID that it finds in the external files. This mode is also
how gSUB has been working in versions <= 0.63.
Settings for this to work is:
UseExternalChannels 2 or 1   <-- set in override or fallback, depending if you like to search gSUB.channels
                                 before or after gSUB is searching the transport stream, 0 - disable.
UseExternalAudio 1           <-- Must be enabled to have effect at all, 0 - disable.
ExternalSearchMode 1         <-- This is the "mode"... 1 = ServiceID must match to find setting
                                 It is valid in both gSUB.audio and gSUB.channels.


Hidden features
===============
Disable gSUB subtitles by executing "touch /tmp/.gSUB_Disable" and reenable it again
by executing "rm /tmp/.gSUB_Disable". This is what the Enable/Disable in the gSUBConf
does. This feature could easily be implemented in other places in the GUI of Enigma/other tools.

Summary: While there is a file "/tmp/.gSUB_Disable" the gSUB will NOT render anything 
on the screen. Everything else is operating as usual.


gSUB.conf Sample
================
This is the file where all settings for gSUB is stored. It is only ready at startup of gSUB so you will need to
restart gSUB if you like your changes to take effect. Note that this is all handled by the GUI if you are using 
that to configure gSUB. 

## gSUB.conf
##
## For gSUB Version 0.74
##
## gSUB Config file, Note that it is VERY case sensitive...be careful!
## This file should be located at /var/tuxbox/config/gSUB/gSUB.conf

# Type 2 Subs, if TS supports it could be used as "5" for Hearing Impaired Subs as well... NOT TESTED!
SubtileType 2

# Language: tested with "swe", "dan", "fin" and "nor". NOT TESTED but implemented: german = "deu" or "ger"
Language swe

# Secondary Language: tested with "swe", "dan", "fin" and "nor". NOT TESTED but implemented: german = "deu" or "ger"
SecondLanguage eng

# Recording delay: When playing recored files a delay for when the subs are show is given here, in seconds.
RecDelay 2

# Suspend While Recording: Set this to 1 to have gSUB sleep while recording, 2 to Kill gSUB totally.
SuspendWhileRecording 2

# Adjust these to get the subs to move a little, 
# X=0 and Y=0 gives a good pos for 4:3 TV's. To move up, use a negative Y-value, left is negative X value.
StartYPos 0
WideStartYPos 0
StartXPos 0

# This has higher priority than StartXPos...so if this is 1, the StartXPos is ignored
CenterText 1

# Palette index...for a standard enigma skin 24-31 is black faded to white (i.e. shades of gray)
TextColor 31

# Palette index...for a standard enigma skin 24-31 is black faded to white (i.e. shades of gray)
OutlineColor 24

# Outline size in pixels 1,2 or 3
OutlineSize 2

# Use background instead of outline, i.e. the "black box"
UseBackground 1

# Font size, NOT height in pixels! If you change font test these out
FontSize 40
WideFontSize 40

# Row Space, i.e the extra space between each row.
RowSpace 6
WideRowSpace 6

# The font you want to use, must be a True-Type font, i.e. end with .ttf
# Use /share/fonts/ or /var/share/fonts/ as paths. These are the ones used by gSUB Configurator.
Font /share/fonts/pakenham.ttf

# Enable/Disable External channels through gSUB.channels, 2- Enabled as override, 1-Enabled as fallback, 0-Disabled
UseExternalChannels 2

# Enable/Disable External audio settings through gSUB.audio, 1-Enabled, 0-Disabled
UseExternalAudio 1

# External search mode for gSUB.channels and gSUB.audio: 0 - LANGUAGE + SID, 1 - SID (as in <=0.63)
ExternalSearchMode 0

# AutostartMode: 0 - Normal (start both daemon and gSUB app), 1 - Start only daemon
AutostartMode 0

# Login stuff...gSUB uses the WebIF to find out some things it needs...
WebLogin root
WebPassword dreambox
WebPort 80


gSUB.channels
==============
If you have a channel that is not displaying subs it might be a simple bug in 
gSUB...if you suspect this, contact the author! But, it might also be so that
the subs are not announced correctly in the transport stream. If this is the 
case, you can add this channel to the gSUB.channels file. What you need is the
Service ID (SID), the Teletext PID (VPID) and the subtitle page. SID & VPID can
be found by executing this in a browser: http://youriptothedreambox/cgi-bin/status

Setting this to "override" or "fallback" (in gSUB.conf) is a way to tell gSUB if you
want to read this file BEFORE (override mode) it scans the transport stream for channels,
or if it should use it after it did not find anything the transport stream (i.e. fallback
mode).

"Service ID only" mode:
-----------------------
The language setting in this file (gSUB.channels) only selects a charset for
gSUB so that it can handle special signs. You can still have other languages selected
as your default languages. I.e. you can have "Swedish" as first, "English" as second 
language but still use "esl" or "fin" in gSUB.channels to get Spanish or Finish subs.

"Language + Service ID" mode:
-----------------------------
When this mode is used, gSUB must find both the Service ID (from the current channel) as
well as one of your selected languages in gSUB.conf to start use this setting. This means
that gSUB will only show shubtitles from the selected languages only in this mode.

When you have the information...just add to gSUB.channels like this sample (note that this
is not the latest version, see the included file in this release for that):
## gSUB.channels
##
## For gSUB Version 0.68
##
## If the subs are not presented in the stream so that gSUB can find them. 
## Simply add them here! MAKE SURE YOU ADD ServiceID and TeletextPID in hexadecimal numbers!
##
## This file should be located at /var/tuxbox/config/gSUB/gSUB.channels
##
## /Gruffy
##

## In this file, the SVT1 and SVT2 for the Boxer Network in Sweden is added as samples, 
## but they are "disabled" by adding "##" in front of them!
## The text behind the numbers can be anything...it is NOT used by gSUB

## Syntax:
## SID(in hex) PID(in hex) PAGE(decimal) LANGUAGE(three letters) Whatever_you_like_can_come_here

## Sweden - Boxer - Gruffy's test stuff 
##3f2 3ec 199 swe - SVT1 for Boxer Network
##13ec 3ec 299 swe - SVT2 for Boxer Network

## Finland extra channels
11 242 451 fin - YLE TV1
21 242 452 fin - YLE TV2
91 242 453 fin - YLE Teema
81 242 454 fin - YLE24
51 242 771 fin - YLE FST

## D+ Spain on 19.2 East
7696 47 801 esl - Taq8
7567 38 801 esl - Taq7
7566 41 801 esl - Taq6
7565 20 801 esl - Taq5
7691 35 801 esl - Taq4
7690 41 801 esl - Taq3
768f 3e 801 esl - Taq2
768e 38 801 esl - Taq1
76c0 20 801 esl - C+
76ca 38 801 esl - C+2
778a 35 801 esl - C+30
7472 26 801 esl - C+ Cine1
7473 29 801 esl - C+ Cine2
7474 3e 801 esl - C+ Cine3
74fe 20 801 esl - Cinemania
74ff 23 801 esl - Cinemania 2
760c 2f 801 esl - Cinemania Clasico
77bd 29 801 esl - Cinemania...30
6f6e 2c 801 esl - TCM
772e 29 801 esl - Calle 13
7503 2f 801 esl - FOX
7504 32 801 esl - AXN

## D+ Spain on 30 West
1 20 801 esl - C+
2 38 801 esl - C+2
3 35 801 esl - C+30
4 26 801 esl - C+ Cine1
6 29 801 esl - C+ Cine2
7 3e 801 esl - C+ Cine3
b 20 801 esl - Cinemana
c 23 801 esl - Cinemana 2
d 3b 801 esl - Cinemana...30
e 2f 801 esl - Cinemana Clasico
f 1093 801 esl - TCM
14 29 801 esl - Calle 13
15 2f 801 esl - FOX
16 3e 801 esl - AXN
65 38 801 esl - Taq1
66 3e 801 esl - Taq2
67 41 801 esl - Taq3
68 35 801 esl - Taq4
69 20 801 esl - Taq5
6a 41 801 esl - Taq6
6b 38 801 esl - Taq7
6c 47 801 esl - Taq8

## TPS/Multivision France on 13 East
4b8 348 889 fre - TPS Cinecomedy
4b9 3ac 889 fre - TPS Cineclub
4b5 21c 889 fre - TPS Cineculte
4b7 2e4 889 fre - TPS Cinefamily
4b3 154 889 fre - TPS Cinetoile
4b6 280 889 fre - TPS Cinextreme
4b1 08c 889 fre - TPS Cinstar
4b2 0f0 889 fre - TPS Homecinma
4b4 1b8 889 fre - TPS Star
515 008 889 fre - Multivision 1
516 0f0 889 fre - Multivision 2
517 154 889 fre - Multivision 3
518 1b8 889 fre - Multivision 4
519 21c 889 fre - Multivision 5
51a 280 889 fre - Multivision 6
51b 2e4 889 fre - Multivision 7

## Canal+ France on 19.2 East
2009 20 889 fre - Canal+
200b 26 889 fre - Canal+ Cinema
200a 23 889 fre - Canal+ Decale
200c 29 889 fre - Canal+ Hi-Tec
2010 35 889 fre - Canal+ Sport
20d2 23 889 fre - KIOSQUE 2
20d3 26 889 fre - KIOSQUE 3
20d4 29 889 fre - KIOSQUE 4
20d5 2c 889 fre - KIOSQUE 5
20d6 2f 889 fre - KIOSQUE 6
20d7 32 889 fre - KIOSQUE 7
20d8 35 889 fre - KIOSQUE 8
20d9 38 889 fre - KIOSQUE 9
20da 3b 889 fre - KIOSQUE 10
226b 3e 889 fre - KIOSQUE 11
20dd 20 889 fre - KIOSQUE 12
2143 3e 889 fre - KIOSQUE 13
20db 32 889 fre - KIOSQUE 14
20dc 35 889 fre - KIOSQUE 15

# Orf on 19.2 East
32c9 0a5 777 deu - Orf1
32ca 1f9 777 deu - Orf2

# Jetix on 1 West
198 12f 693 dan


gSUB.audio
==========
Working like the gSUB.channels but used to set correct audio settings selection 
for certain channels where you need to select, not only the PID but also LEFT/RIGHT
channel to get only one language. Note that this file is using the "Service ID only"
mode as well as "Language + Service ID" mode. The same rules apply.

See this sample (note that this is not the latest version, see the included file 
in this release for that):

## gSUB.audio
##
## For gSUB Version 0.68
##
## With this channel you can have gSUB to change audio settings
## SID = Service ID (same as in gSUB.channels)
## APID = Audio PID (Some channels will let you select between more than one AUDIO PIDs)
## CHANNEL = 0,1,2  (0=left, 1=stereo, 2=right)
## LANG = Country code for this audio setting
##
## Use "##" infront of settings you don't like to use. By default..all are disabled!
## 
## SID APID CHANNEL LANG - Bla bla bla

## Swedish Audio, Canal Digital 1W 
192 2BE 0 swe - Cartoon Network
198 44D 0 swe - Jetix
0CE 281 0 swe - Nickelodeon
389 284 0 swe - Eurosport
0c9 191 0 swe - National Geografic

## Norwegian Audio, Canal Digital 1 West
192 2be 2 nor - Cartoon Network
198 44d 2 nor - Jetix
0ce 281 2 nor - Nickelodeon
389 285 0 nor - Eurosport 
0c9 191 2 nor - National Geografic

## Danish Audio, Canal Digital 1 West
192 2bd 2 dan - Cartoon Network
0ce 280 0 dan - Nickelodeon 
198 44e 0 dan - Jetix
389 284 2 dan - Eurosport
0c9 192 2 dan - National Geografic

## English Audio, Canal Digital 1 West
192 2bd 0 eng - Cartoon Network
0ce 280 2 eng - Nickelodeon 
198 44e 2 eng - Jetix
389 285 2 eng - Eurosport
0c9 192 0 eng - National Geografic
