::

                  __________         _________
     ______ ___.__\______   \ ____  /   _____/ ____  ____   ____   ____
     \____ <   |  ||       __/ __ \ \_____  \_/ ____/ __ \ /    \_/ __ \
     |  |_> \___  ||    |   \  ___/ /        \  \__\  ___/|   |  \  ___/
     |   __// ____||____|_  /\___  /_______  /\___  \___  |___|  /\___  >
     |__|   \/            \/     \/        \/     \/    \/     \/     \/
    

General Information
===================

**pyReScene** is a port of ReScene .NET to the Python programming language,
but by now many new features, improvements and scripts have been added.
ReScene is a mechanism for backing up and restoring the metadata from "scene" 
released RAR files. RAR archive volumes are rebuild using the stored metadata 
in the SRR file and the extracted files from the RAR archive. This process
only worked on RAR files created with "Store" mode (otherwise known as 
-m0 or No Compression), but since pyReScene version 0.4 this is also possible
for various other compression settings. However, it is not guaranteed that
reconstruction of compressed archives is always possible. Also a handful of
known bugs related to this still exist. pyReScene consists of multiple 
related tools and scripts.

**pyReSample** is a companion to ReScene. It does for samples what ReScene does 
for RARs. You can use ReSample to build a blueprint of an *AVI*, *MKV*, *MP4* or *WMV*
sample, and then use that blueprint (the .srs file) with the full video file
to recreate that sample. It contains backups of all parts of the sample file 
that are not the actual track data as well as a signature that helps ReSample 
locate the missing track data from the full video file.

Also *MP3* and *FLAC* music files are supported. The tags with all the meta data
are copied to the SRS file. This can be restored at another time. *fpcalc*
must be available in your path to use this feature. It can be downloaded from
https://bitbucket.org/acoustid/chromaprint/downloads. This tool creates 120s
AcoustID music fingerprints. http://acoustid.org/chromaprint

The SRS of *VOB* and *M2TS* files are very small. They serve as verification
of the sample data stream. The VOB SRS can rebuild the sample, but with
M2TS this will always fail.

**pyReScene Auto** makes it all a bit easier: one command to create an SRR file.
It does not require write access to the release directories and it can create
SRR files of your whole collection!
(Create and mount a private file share to force the read only behavior
in Windows. This way you can be absolutely sure!)

**pyReScene Usenet** is able to create SRR files from NZB files. It works by
downloading only (parts of) the segments it needs for creating an SRR file.
srr_usenet.py and other NZB related scripts are located in the usenet 
directory. The compiled _yenc.so module (for more speed) can be obtained from 
http://pypi.python.org/pypi/yenc/. Create a srr_usenet.cfg configuration file 
in the usenet directory for easy usage. A template example file is available.

Some related external tools are included into the repository:

* **Awescript** is a Usenet downloads post processing script made by Guber. It is
  able to create SRR files and extract RAR archives.

* **Rerar** is a tool written in Python 3 by Vadmium to re-create sets of 
  uncompressed rar files. It can also report the metadata and parameters 
  stored in a rar file. It should be able to exactly re-create many real-world 
  RAR files if the right input parameters and metadata are known.

View ``srr_spec.txt`` and http://rescene.wikidot.com/ for more info.

Dependencies
============

- Python (http://www.activestate.com/activepython)
- Chromaprint* (https://acoustid.org/chromaprint)
- UnRAR* (http://www.rarlab.com/download.htm) or unrar-nonfree(!) on Debian
- Shareware WinRAR setup files* (http://rescene.wikidot.com/rar-versions)

    `* Works without, but required for certain functionality.`

pyReScene requires Python 2.6, 2.7, or 3 to run. There are some executables
made available for Windows users. fpcalc is necessary for creating 
music SRS files. If you want to try reconstructing compressed RAR volumes, 
you will need to obtain a couple of the shareware (Win)RAR packages.
These files will need to be preprocessed by the bin/preprardir.py script.
This script extracts the RAR executables from the archives and renames them
for further usage. The new folder with RAR executables will need to be passed
to the -z parameter of ReScene when reconstructing compressed archives.
UnRAR.exe or its Linux equivalent is required for SRR creation of vobsubs.

Installation instructions
=========================

``python setup.py install``

Install chromaprint from your repository or put the fpcalc executable
somewhere in your path. It will also work if you put it in the ./bin or
./resample directory.

Windows installation instructions
---------------------------------

Install Python 3. Download it from http://www.activestate.com/activepython
Install it to C:\\Python33\\ for example.

Place the source somewhere on your hard disk. e.g. C:\\pyReScene\\

Add the bin\\windows directory to your path.

* Run ``add_current_dir_to_path.bat`` that you can find in that directory.
  It'll prepend your SYSTEM path.
* Or add it manually: http://www.computerhope.com/issues/ch000549.htm

Done! Now you will be able to call ``pyrescene`` from any directory.

Another way, but it's better to not mess with Windows folders!
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Copy the .bat to a folder that is in your PATH, e.g. C:\\Windows\\System32\\ [1]_

Edit the .bat files to reflect the path where Python and the script source code
is located: e.g. ``C:\Python33\python.exe C:\pyReScene\bin\srr %*``

.. [1] *If .exe files are placed in C:\\Windows\\System32\\ and they fail to run,
   move them to C:\\Windows\\SysWOW64\\.
   Even better would be to use your own folder you've added to the PATH!*

Linux installation instructions
-------------------------------

Make sure you can run the 32 bit rar binaries when you try to reconstruct
compressed rar archives: http://rescene.wikidot.com/faq#x64

Tutorials
=========

Do ``tool_name --help`` to see all the available options.

A one stop solution to create SRR files is the following command:

  ``python pyrescene.py -r --best /root/directory/to/check``

  This command will recursively check /root/directory/to/check for scene
  releases. Sample files are checked against the main movie files (-s) and SRR
  files for compressed RARs are also created (-c). An SRR file for vobsubs
  will be created recursively if unrar can be found (-v). --best: -c -s -v
      
To create a .srr file for vobsubs, do:

  ``python pyrescene.py --vobsubs file.sfv``

  Pointing to the .rar file works too and 
  Windows users can use the vs.bat shortcut.

http://rescene.wikidot.com/tutorials has some more tutorials.

For the paranoid
================

This is a list of security considerations someone reluctant to use pyReScene
to create SRR files should know about.

* pyReScene Auto does not make any external network connections.
* pyReScene Auto does not need write access to the location of the release
  file. SRR files can be put into the release directory if wanted though.
* A temporary folder is used for SRR creation. By default it uses the location
  ``tempfile.mkdtemp()`` provides. On Windows systems this is somewhere in the
  AppData folder and "The directory is readable, writable, and searchable
  only by the creating user." A custom temporary directory can be provided with
  the ``-t`` parameter. Due to unknown bugs, "SRR-xxxxxx" folders could be 
  left behind in the temporary folder when the tool crashes. Tell me about this!
* When .srs creation fails, a .txt file will be included into the .srr with
  some basic information instead. Due to an unknown bug/crash, this could
  include paths to the location of the .py or .exe files on your system.
  Use non-descriptive paths or the default installation location on Unix systems.
* A site nfo will be included if encountered.
  Use ``--skip-regex`` to skip over custom files and folders.
* Log files of known programs are never included. e.g. rushchk.log
* SFV files can include the creating tool info if they aren't raped yet.
  This is a good thing for the project! But it could reveal source of origin
  of these excellent SRRs to those close to the origin.
  Hamster them for a while.
* Same for NFO files: e.g. trailing whitespace could not be stripped yet.

Whatever your objections, create SRRs now.
In time all will become irrelevant anyway ;)

What's new?
===========

Read the *NEWS* file.

Who wrote this?
===============

Check the *AUTHORS* file.

Where can I get help?
=====================

- Read the `FAQ`_ 
- Check out the `tutorials`_ 
- `Forum`_
- Chat: `#srrdb`_ on EFNet

.. _FAQ: http://rescene.wikidot.com/faq
.. _tutorials: http://rescene.wikidot.com/tutorials
.. _Forum: http://rescene.wikidot.com/forum:start
.. _#srrdb: irc://irc.efnet.org/%23srrdb

Do contribute to srrdb.com and help us to motivate the right people! --Gfy