video-in-place-hevc-converter/README.md

# Convert videos in-place to h265 (HEVC)

This is a simple ruby script that will chuch through a directory converting all of the videos to use h.265 or HEVC in place. This works by converting the video file to \*.tmp.mp4, and then moving it to its original file name with the mp4 extension. It will delete the old version of the file.  


## Usage

This is a long running ruby script, it makes calls to FFMPEG using a ruby gem to scrape metadata of videos, and transcode them. It works by appling some simple filters to create a list of videos that can be converted, and then works through that queue.

Change to the directory, where the config and script is located then run: `$ ruby convertVideos.rb start`


## Example Config
Please note the preceding colons are important. Also the file must be called config.yml

```
:directory: /mnt/movies
:min_age_days: 5
:log_location: /home/user/logs/hevc_conversion.log
:preset: slow
:threads: 8
:max_new_file_size_ratio: 0.9
```

| Configuration | Description |
| -------- | -------- |
| directory | The directory to recurse into.  All files will be considered within that directory. |
|min_age_days | How many days old does this file have to be to be considered for conversion.  |
|log_location|  This Script is designed to run deetached in the background. As such the log location is the best way to figure out whatis going on and the status of the conversion |  
| preset | used to trade off between final file size, quality, and transcoding time. I recomend slow. See ffmpeg docs for more detail. |
|threads | How many threads should be used for converting the file.  |
|max_new_file_size_ratio| Once transocing an individual file is finished, this script will make sure the output is smaller than the origional.  Spesifically new file size <= Old file size * this value. Since transcoding always involves quality loss this value should be less than 1.0 |


## Coridnation
When this script starts to convert a video, it creates a .filename.tmp.mp4 file that used the old files filename.  This acts as kind of a lock because the exitsance of that file is checked before conversion. This also allows us to save state between runs without needing to share a database or other coridination servcie. That file is left behind if, for any reason, the conversion fails, the process is stopped, or if afterthe conversion the new HEVC file is not at least 10% smaller than the origional. The content is replace with an explination if possible.

It also makes it so multiple computers can run this script, provided they are all run against the same backing file system (SMB, NFS, etc.).  There is a risk of duplicate work if two processes try to start to transcode the same file at the same time, but this risk is minimal for large libraries. To further mitigate, the list of candidate files is randomaized.


## Setup

1. Instal Ruby 2.1.0+
2. Install (ffmpeg)[https://ffmpeg.org/download.html] near version 3.4.4  `# apt-get install ffmpeg`
3. `$ gem install bundler`
4. `$ bundle install`
5. Optional: Install screen or tmux. This is to allows it to run in the background after closing SSH on a server. 
6. Edit the script if you want.
7. Run the script.
8. Automate it e.g. with cron?


## Disclaimers
- Only use with videos you have the rights to copy
- This will delete the original video, so use with care. Test with a test directory before running on your entire library.  
- Use a test file with all your media playing devices to ensure that they can handle HEVC encoding.