serieSandSubs
===============

Description
-----------

This program has three main functions:
* subtitle distribution
* series management
* memorize the playback position of the media files

1. Subtitle distribution
This was the main reason why I created the program. Cause I can't read the movie and series subtitles I searched for a possibility to make them accessible.
The best solution for that seems to send the subtitles via XMPP. So it's possible to receive them by
any device which can handle the XMPP protocol.

You must create at least two accounts: one for the sender and another for the recipient and enter
their data into the serieSandSubs.conf file in the config folder. If you have no jabber accounts yet
you can either create them for example at www.jabber.org or setup an own jabber server called
ejabberd (easy for Debian).

I receive the subs with my iPhone and the app IM+. This app works great with the screen reader VoiceOver. The incoming messages are spoken automatically.
At the moment you need .srt subtitle files as source. For german subs I can recommend www..subcentral.de

2. Series manager
The program memorizes the currently watched episode of a series so it's not longer necessary to guess, if you already watched episode 10 or not. If you start it without any parameters, it lists all resumable series.
But a series must be added by hand. To do this you use the parameter "-a" and then enter the first episode file name.

3. Regardless if it's a series or not the system will memorize the playback position of all media files. So it's easy to resume a half watched video or audio book. This is done automatically when you start the playback again. If you want to play the file from beginning, use the -f parameter.

The other file in the config menu named input.conf does not directly belong to my program. It's a MPlayer config file where the user can  specify shortcuts for MPlayer functions.

I've defined:
* s: to jump between audio streams if more than one is available (often used to change the language)
* n: to set the playback speed back to normal (can be changed with [] and {})


Dependencies
------------

Linux based operating system
Python version >= 2.7
The installer for python modules (easy_install / setuptools)
MPlayer
pandoc for stripping html tags from subtitle file

Python modules
* sleekxmpp: XMPP library
* magic: get the encoding of text files
* ConfigOBJ: Parse and write ini files

A few optional python packages
* pyasn1: For the verification of SSL certificates
* dnspython: look up domain names


Installation
------------

1. sudo apt-get install python-pyasn1 python-dnspython python-setuptools mplayer git pandoc
2. sudo easy_install python-magic sleekxmpp configobj
3. git clone https://github.com/scheibler/serieSandSubs.git
4. Copy the config files from the config folder into the MPlayer folder ~/.mplayer/
5. start the program either with "python serieSandSubs/src/main.py" or "./serieSandSubs/src/main.py"

Usage
-----

You can use MPlayer's standard key combinations to control the playback. The subtitle sending starts
automatically, if you activated it in the serieSandSubs.conf file and if the Mplayer finds a .srt
file in the video file directory. You can toggle the visibility and sending of the subtitles by
pressing "v". It's also possible to manually specify a subtitle file with the "-s" option.

With "./main.py -a /path/to/series/season1/episode1.avi" you add a series to the series manager. If
you later run "./main.py" you get all added series and their positions. After you watched the last
episode of the "season1" folder, the entry in the series manager is deleted automatically. To
prevent that you must add the "-p" option to the add command above. This is useful, if a season is
not complete yet.  This only must be done ones during adding.

If you want to watch more than one episode, you can use "-c" for continuous playback.

You can also activate a sleep timer with the command line option "-t". If activated, you hear a beep
sound before the player is stopped. If you pause the video for one second, the system knows, that
you're still awake and continues playback. After three beeps (interval 10 seconds) the Mplayer stops
and remembers the position. The time between the interactions can be defined in the config file.
Therewith this can work you must copy the beep.ogg file in the config folder in the Mplayer folder
(~/.mplayer).

The program awaits the subtitle files in a UTF-8 encoding. To check the file encoding you can use:
file subtitle_file.srt
If your downloaded file is not UTF-8 encoded, convert it first, for example, the following command
works for many western european languages:
iconv -f ISO-8859-1 -t UTF-8 input.srt -o output.srt
This conversion is automatically done for ISO-8859-1 encoded subtitle files.

If the subtitle file does not match the video file exactly, you can specify an offset delay in seconds with
the -d option. For example this could be necessary, if the video file starts with a trailer or a summery of
previously happened scenes but the subtitles directly begin with the movie. The delay is a floating
point number and can be positive or negative.