Formulate README as manual

Readme.org

@@ -0,0 +1,99 @@
+#+title: Dvd Rip
+
+* How it works
+This project is divided in two separate parts,
+the =ripper= and the =transcoder=.
+
+The idea is to run the =ripper= manually, which just copies the inserted dvd,
+then you =transfer= the files to the =transcoder=.
+This can just be the one on your local machine, or you can have this project cloned onto a server, which then does the transcoding automatically 24/7.
+
+** Ripping
+To do the ripping, enter the =ripper= directory and run ~./rip_dvd.py <args>~.
+The most important argument is the type of the dvd, either =movie= or =series=, and the name of the movie or series you are ripping.
+
+*** Directory structure
+#+begin_example
+.
+├── bell.oga           # The sound to be played when ripping has finished
+├── rip_dvd.py         # The ripper script
+├── rip.log            # Logs all ripping attempts
+├── ripped
+│   ├── movie          # The ripped movies
+│   └── series         # The ripped series
+├── tmp                # The ripped files while ripping has not yet finished.
+│                        # If the script has been terminated, this might not get deleted.
+│                        # In this case just remove it yourselves.
+└── transfer_ripped.py # The transfer script
+#+end_example
+
+** Transfer
+To transfer the ripped files to the =transcoder=, enter the =ripper= directory and run ~./transfer_ripped.py~.
+This will rsync all the ripped files to the ~$TRANSFER_DESTINATION_FOLDER~ (see [[*Configuration][Configuration]]) which may be on an external server which then will =transcode= them into video files.
+
+Note while the transfer is in progress, the script will create =movie_title.lock= files in source and destination folder to indicate the transfer is yet incomplete.
+The transcoder will not try to transcode data for which the =.lock= file exists.
+
+** Transcoding
+To transcode the ripped files, enter the =transcoder= directory, then run ~./transcode_dvd.py~.
+This will try to transcode all the files in the =raw= folder and put the results in the =transcoded= folder.
+While transcoding is in progress you can see the live log produced by handbrake by running ~tail -f raw/movie_title.log~.
+
+You can also run this in a systemd service. For this see the =video_transcoder.service.sample= file.
+
+*** Directory structure
+#+begin_example
+.
+├── transcode_dvd.py                # The transcode script
+├── transcode.log                   # Logs all transcoding attempts
+├── raw                             # The transfer_ripped.py script should transfer all ripped files here
+│   ├── movie
+│   └── series
+├── transcoded
+│   ├── movie                       # The transcoded movies
+│   └── series                      # The transcoded series
+├── tmp                             # The transcoded files while transcoding has not yet finished.
+│                                     # In case of an error during transcoding, this might not get deleted.
+│                                     # In this case just remove it yourselves.
+└── video_transcoder.service.sample # The sample systemd service file
+#+end_example
+
+*** Fixing transcoding errors
+When there was an error transcoding you will see an =movie_title.err.log= file in the =raw= folder.
+This will include the handbrake logs telling you what has gone wrong.
+After you have fixed the error, delete the =movie_title.err.log= file and the =transcoder= will re-attempt transcoding of the movie on the next run.
+
+**** Series errors
+When transcoding series, a common error is that there are more video tracks on the dvd than you specified there are episodes on the dvd.
+Whether this is the case, you can see at the bottom of the =series_title.err.log= file.
+
+To fix this, find out which tracks correspond to the episodes on the dvd, then create a =series_title.titles= file in the =raw= folder.
+In this file specify the track numbers one per line.
+
+For example your series file is called =Lost_S01_E01-04=, but the dvd has 5 tracks.
+Assuming track 1 is just a bonus scene you do not want ripped, create =Lost_S01_E01-04.titles=:
+
+#+begin_example
+2
+3
+4
+5
+#+end_example
+
+Then delete the =Lost_S01_E01-04.err.log= file and the transcoder will retry the transcoding using just titles 2-5 on its next run.
+
+* Configuration
+ Configuration is done via an =.env= file. For this, just do ~cp .env.sample .env~ and edit the =.env= file to your liking.
+ When using an server for transcoding, edit the =TRANSFER_DESTINATION_FOLDER= value.
+ Its default is to transfer the files to the =transcoder/raw= folder of the current project.
+
+* Dependencies
+- dvdbackup (=ripper=)
+- rsync (=ripper=)
+- libnotify (=ripper=)
+- handbrake (=transcoder=)
+- python3 with dependencies listed in =requirements.txt= (both)
+
+** Nix dev-shell
+If you use nix you can use the =flake.nix= via ~nix develop~.
+In case you also use direnv, just run ~direnv allow .~.

requirements.txt

@@ -1,3 +1,3 @@
-# playsound
+playsound
 # pygobject # dependency of playsound
 python-dotenv

ripper/rip_dvd.py

@@ -63,7 +63,7 @@ def parse_args():
     )
     parser.add_argument(
         "title",
-        help='The title of the movie. Series must end with "Sx Ex-x". E.g.: "Lost S01 E1-04"',
+        help='The title of the movie. Series must end with "Sx Ex-x". E.g.: "Lost S01 E1-04" or "Lost_S2_E2"',
     )
     parser.add_argument(
         "--dev",