add subaligner_tune cli for advanced users and fix console_scripts in…

…stallation

.gitignore

@@ -13,6 +13,7 @@ tests/subaligner/resource/*_aligned.*
 tests/subaligner/resource/test_mono.wav
 tests/subaligner/training.log
 tests/subaligner/output.log
+*-output*
 *training.log*
 *output.log*
 *.prof

Makefile

@@ -37,9 +37,11 @@ install:
 	cp ./bin/subaligner .$(PYTHON)/bin/subaligner
 
 uninstall:
+	rm -f .$(PYTHON)/bin/subaligner
 	rm -f .$(PYTHON)/bin/subaligner_1pass
 	rm -f .$(PYTHON)/bin/subaligner_2pass
-	rm -f .$(PYTHON)/bin/subaligner
+	rm -f .$(PYTHON)/bin/subaligner_train
+	rm -f .$(PYTHON)/bin/subaligner_tune
 
 build-gzip:
 	mkdir -p dist
@@ -55,7 +57,7 @@ test:
 	cat requirements.txt | xargs -L 1 .$(PYTHON)/bin/pip install; \
 	cat requirements-dev.txt | xargs -L 1 .$(PYTHON)/bin/pip install
 	PYTHONPATH=. .$(PYTHON)/bin/python -m unittest discover
-	-.$(PYTHON)/bin/pycodestyle subaligner tests examples misc bin/subaligner_1pass bin/subaligner_2pass bin/subaligner bin/subaligner_train --ignore=E203,E501,W503
+	-.$(PYTHON)/bin/pycodestyle subaligner tests examples misc bin/subaligner bin/subaligner_1pass bin/subaligner_2pass bin/subaligner_train  bin/subaligner_tune setup.py --ignore=E203,E501,W503
 
 test-all: ## run tests on every Python version with tox
 	.$(PYTHON)/bin/tox

README.md

@@ -93,7 +93,14 @@ The aligned subtitle will be saved at `subtitle_aligned.srt`. For details on CLI
 ## Supported Formats
 Subtitle: SubRip, TTML, WebVTT, (Advanced) SubStation Alpha, MicroDVD, MPL2 and TMP
 
-Video: MP4, WebM, Ogg, 3GP, FLV and MOV 
+Video: MP4, WebM, Ogg, 3GP, FLV and MOV
+
+## Advanced Usage
+You can train a new model with your own audiovisual files and subtitle files:
+```
+$ subaligner_train -vd VIDEO_DIRECTORY -sd SUBTITLE_DIRECTORY -od OUTPUT_DIRECTORY
+```
+Then you can apply it to your subtitle synchronisation with the aforementioned commands. For more details on how to train and tune your own model, please refer to [Subaligner Docs](https://subaligner.readthedocs.io/en/latest/advanced_usage.html).
 
 ## Anatomy
 Subtitles can be out of sync with their companion audiovisual media files for a variety of causes including latency introduced by Speech-To-Text on live streams or calibration and rectification involving human intervention during post-production.

bin/subaligner_tune

@@ -0,0 +1 @@
+../subaligner/subaligner_tune/__main__.py

examples/tune_hparams.py

@@ -1,8 +1,5 @@
 import os
-from subaligner.hyperparameters import Hyperparameters
 from subaligner.hparam_tuner import HyperParameterTuner
-from subaligner.embedder import FeatureEmbedder
-from subaligner.trainer import Trainer
 
 if __name__ == "__main__":
     examples_dir = os.path.dirname(os.path.abspath(__file__))
@@ -11,18 +8,7 @@
     video_file_path = os.path.join(examples_dir, "..", "tests/subaligner/resource/test.mp4")
     srt_file_path = os.path.join(examples_dir, "..", "tests/subaligner/resource/test.srt")
 
-    hyperparameters = Hyperparameters()
     hparam_tuner = HyperParameterTuner([video_file_path], [srt_file_path], output_dir)
     hparam_tuner.tune_hyperparameters()
-    tuned_hyperparameters = hparam_tuner.hyperparameters
-    tuned_hyperparameters.epochs = 10
 
-    trainer = Trainer(FeatureEmbedder())
-    trainer.train([video_file_path],
-                  [srt_file_path],
-                  output_dir,
-                  output_dir,
-                  output_dir,
-                  output_dir,
-                  output_dir,
-                  tuned_hyperparameters)
+    print(hparam_tuner.hyperparameters.to_json())

setup.py

@@ -23,10 +23,10 @@
       author="Xi Bai",
       author_email="[email protected]",
       classifiers=[
-        "License :: OSI Approved :: MIT License",
-        "Programming Language :: Python :: 3.6",
-        "Programming Language :: Python :: 3.7",
-        "Programming Language :: Python :: 3.8"
+          "License :: OSI Approved :: MIT License",
+          "Programming Language :: Python :: 3.6",
+          "Programming Language :: Python :: 3.7",
+          "Programming Language :: Python :: 3.8"
       ],
       license="MIT",
       url="https://subaligner.readthedocs.io/en/latest/",
@@ -37,6 +37,10 @@
       package_dir={"subaligner": "subaligner"},
       packages=[
           "subaligner",
+          "subaligner.subaligner_1pass",
+          "subaligner.subaligner_2pass",
+          "subaligner.subaligner_train",
+          "subaligner.subaligner_tune",
           "subaligner.models.training.model",
           "subaligner.models.training.weights",
           "subaligner.models.training.config",
@@ -49,13 +53,18 @@
       install_requires=requirements,
       test_suite="tests.subaligner",
       setup_requires=["numpy>=1.14.1,<1.18.0"],
-      scripts=["bin/subaligner_1pass", "bin/subaligner_2pass", "bin/subaligner", "bin/subaligner_train"],
-      entry_points= {
+      scripts=[
+          "bin/subaligner",
+          "bin/subaligner_1pass",
+          "bin/subaligner_2pass",
+          "bin/subaligner_train",
+          "bin/subaligner_tune",
+      ],
+      entry_points={
           "console_scripts": [
-              "subaligner_1pass=subaligner.subaligner_1pass",
-              "subaligner_2pass=subaligner.subaligner_2pass",
               "subaligner=subaligner.__main__:main",
-              "subaligner_train=subaligner.subaligner_train",
-          ]
-      },
-)
+              "subaligner_1pass=subaligner.subaligner_1pass.__main__:main",
+              "subaligner_2pass=subaligner.subaligner_2pass.__main__:main",
+              "subaligner_train=subaligner.subaligner_train.__main__:main",
+              "subaligner_tune=subaligner.subaligner_tune.__main__:main",
+          ]})

site/source/advanced_usage.rst

@@ -0,0 +1,71 @@
+########################
+Advanced Usage
+########################
+
+You can train a new model with your own audiovisual files and subtitle files and the model can be
+later used for synchronising subtitles.
+
+**Start a fresh Training**::
+
+    (.venv) $ subaligner_train -vd av_directory -sd subtitle_directory -od output_directory
+
+Make sure each subtitle and its companion audiovisual content are sharing the same base filename, e.g.,
+awesome.mp4 and awesome.srt. Than spit them into a two saperate folders, e.g., av_directory and subtitle_directory.
+The training result will be stored into a specified directory, e.g., output_directory.
+
+**Resume training**::
+
+    (.venv) $ subaligner_train -vd av_directory -sd subtitle_directory -od output_directory -e 200 -r
+
+Training over a large dataset is normally an expensive process. You can resume the previous training with `-r` or `--resume`.
+Make sure the number of epochs you pass in is greater than the epochs done in the past.
+
+**Reuse embeddings**::
+
+    (.venv) $ subaligner_train -vd av_directory -sd subtitle_directory -od output_directory -utd
+
+Embeddings extracted from your media files can be reused with `-utd` or `--use_training_dump`. With the flag on, you can train a new
+model of another kind without going through feature embedding process, which could take quite long to finish.
+
+**Hyper parameters**::
+
+    -bs BATCH_SIZE, --batch_size BATCH_SIZE
+                        Number of 32ms samples at each training step
+    -do DROPOUT, --dropout DROPOUT
+        Dropout rate between 0 and 1 used at the end of each intermediate hidden layer
+    -e EPOCHS, --epochs EPOCHS
+        Total training epochs
+    -p PATIENCE, --patience PATIENCE
+        Number of epochs with no improvement after which training will be stopped
+    -fhs FRONT_HIDDEN_SIZE, --front_hidden_size FRONT_HIDDEN_SIZE
+        Number of neurons in the front LSTM or Conv1D layer
+    -bhs BACK_HIDDEN_SIZE, --back_hidden_size BACK_HIDDEN_SIZE
+        Comma-separated numbers of neurons in the back Dense layers
+    -lr LEARNING_RATE, --learning_rate LEARNING_RATE
+        Learning rate of the optimiser
+    -nt {lstm,bi_lstm,conv_1d}, --network_type {lstm,bi_lstm,conv_1d}
+        Network type
+    -vs VALIDATION_SPLIT, --validation_split VALIDATION_SPLIT
+        Fraction between 0 and 1 of the training data to be used as validation data
+    -o {adadelta,adagrad,adam,adamax,ftrl,nadam,rmsprop,sgd}, --optimizer {adadelta,adagrad,adam,adamax,ftrl,nadam,rmsprop,sgd}
+        TensorFlow optimizer
+
+You can pass in the above flags to manually change hyper parameters before each training. Or You can let Subaligner tune hyper parameters automatically as shown below.
+
+**Hyper parameters tuning**::
+
+     (.venv) $ subaligner_tune -vd av_directory -sd subtitle_directory -od output_directory
+
+You can pass in the following flags to customise the tuning settings:
+
+**Optional custom flags**::
+
+    -ept EPOCHS_PER_TRAIL, --epochs_per_trail EPOCHS_PER_TRAIL
+        Number of training epochs for each trial
+    -t TRAILS, --trails TRAILS
+        Number of tuning trials
+    -nt {lstm,bi_lstm,conv_1d}, --network_type {lstm,bi_lstm,conv_1d}
+        Network type
+    -utd, --use_training_dump
+        Use training dump instead of files in the video or subtitle directory
+

site/source/index.rst

@@ -21,6 +21,7 @@ The source code can be found on GitHub: `subaligner <https://github.com/baxtree/
 
    installation
    usage
+   advanced_usage
    anatomy
    test
    acknowledgement

site/source/installation.rst

@@ -44,9 +44,11 @@ to create a virtual environment and set up all the dependencies:
     $ cd subaligner
     $ make install && source .venv/bin/activate
 
-**subaligner_1pass, subaligner_2pass and subaligner should be on your PATH now**::
+**Subaligner CLI should be on your PATH now**::
 
+    (.venv) $ subaligner --help
     (.venv) $ subaligner_1pass --help
     (.venv) $ subaligner_2pass --help
-    (.venv) $ subaligner --help
+    (.venv) $ subaligner_train --help
+    (.venv) $ subaligner_tune --help
 

subaligner/hparam_tuner.py

@@ -5,10 +5,11 @@
 from .trainer import Trainer
 from .embedder import FeatureEmbedder
 from .hyperparameters import Hyperparameters
+from .network import Network
 
 
 class HyperParameterTuner(object):
-    """Hyper parameter tuning using the Bayesian Optimizer"""
+    """Hyper parameter tuning using the Tree of Parzen Estimators algorithm"""
 
     SEARCH_SPACE = {
         "learning_rate": hp.loguniform("learning_rate", np.log(0.00001), np.log(0.1)),
@@ -25,7 +26,8 @@ def __init__(self,
                  subtitle_file_paths,
                  training_dump_dir,
                  num_of_trials=5,
-                 tuning_epochs=5):
+                 tuning_epochs=5,
+                 network_type=Network.LSTM):
         """Hyper parameter tuner initialiser
 
         Arguments:
@@ -36,12 +38,18 @@ def __init__(self,
         Keyword Arguments:
             num_of_trials {int} -- The number of trials for tuning (default: {5}).
             tuning_epochs {int} -- The number of training epochs for each trial (default: {5}).
+            network_type {string} -- The type of the network (default: {"lstm"}, range: ["lstm", "bi_lstm", "conv_1d"]).
         """
+
+        assert network_type in Network.TYPES, "Supported network type values: %s" % Network.TYPES
+        hyperparameters = Hyperparameters()
+        hyperparameters.network_type = network_type
+        self.__hyperparameters = hyperparameters
+
         self.__trainer = Trainer(FeatureEmbedder())
         self.__av_file_paths = av_file_paths
         self.__subtitle_file_paths = subtitle_file_paths
         self.__training_dump_dir = training_dump_dir
-        self.__hyperparameters = Hyperparameters()
         self.__num_of_trials = num_of_trials
         self.__tuning_epochs = tuning_epochs
         self.__original_epochs = self.__hyperparameters.epochs