1# videocr
  2
  3Extract hardcoded (burned-in) subtitles from videos using the [Tesseract](https://github.com/tesseract-ocr/tesseract) OCR engine with Python.
  4
  5Input a video with hardcoded subtitles:
  6
  7<p float="left">
  8  <img width="430" alt="screenshot" src="https://user-images.githubusercontent.com/10210967/56873658-3b76dd00-6a34-11e9-95c6-cd6edc721f58.png">
  9  <img width="430" alt="screenshot" src="https://user-images.githubusercontent.com/10210967/56873659-3b76dd00-6a34-11e9-97aa-2c3e96fe3a97.png">
 10</p>
 11
 12```python
 13# print_sub.py
 14
 15import videocr
 16
 17if __name__ == '__main__':
 18    print(videocr.get_subtitles('video.mp4', lang='chi_sim+eng',
 19                                sim_threshold=70, conf_threshold=65))
 20```
 21
 22`$ python3 print_sub.py`
 23
 24Output:
 25
 26``` 
 270
 2800:00:01,042 --> 00:00:02,877
 29喝 点 什么 ? 
 30What can I get you?
 31
 321
 3300:00:03,044 --> 00:00:05,463
 34我 不 知道
 35Um, I'm not sure.
 36
 372
 3800:00:08,091 --> 00:00:10,635
 39休闲 时 光 …
 40For relaxing times, make it...
 41
 423
 4300:00:10,677 --> 00:00:12,595
 44三 得 利 时 光
 45Bartender, Bob Suntory time.
 46
 474
 4800:00:14,472 --> 00:00:17,142
 49我 要 一 杯 伏特 加
 50Un, I'll have a vodka tonic.
 51
 525
 5300:00:18,059 --> 00:00:19,019
 54谢谢
 55Laughs Thanks.
 56```
 57
 58## Performance
 59
 60The OCR process is CPU intensive. It takes 3 minutes on my dual-core laptop to extract a 20 seconds video. More CPU cores will make it faster.
 61
 62## Installation
 63
 641. Install [Tesseract](https://github.com/tesseract-ocr/tesseract/wiki) and make sure it is in your `$PATH`
 65
 662. `$ pip install videocr`
 67
 68## Functions
 69
 70```python
 71get_subtitles(
 72    video_path: str, lang='eng', time_start='0:00', time_end='',
 73    conf_threshold=65, sim_threshold=90, use_fullframe=False)
 74```
 75Return the subtitles string in SRT format.
 76
 77
 78```python
 79
 80save_subtitles_to_file(
 81    video_path: str, file_path='subtitle.srt', lang='eng', time_start='0:00', time_end='',
 82    conf_threshold=65, sim_threshold=90, use_fullframe=False)
 83```
 84Write subtitles to `file_path`. If the file does not exist, it will be created automatically.
 85
 86### Parameters
 87
 88- `lang`
 89
 90  The language of the subtitles. You can extract subtitles in almost any language. All language codes on [this page](https://github.com/tesseract-ocr/tesseract/wiki/Data-Files#data-files-for-version-400-november-29-2016) (e.g. `'eng'` for English) and all script names in [this repository](https://github.com/tesseract-ocr/tessdata_fast/tree/master/script) (e.g. `'HanS'` for simplified Chinese) are supported.
 91  
 92  Note that you can use more than one language, e.g. `lang='hin+eng'` for Hindi and English together. 
 93  
 94  Language files will be automatically downloaded to your `~/tessdata`. You can read more about Tesseract language data files on their [wiki page](https://github.com/tesseract-ocr/tesseract/wiki/Data-Files).
 95
 96- `conf_threshold`
 97
 98  Confidence threshold for word predictions. Words with lower confidence than this value will be discarded. The default value `65` is fine for most cases. 
 99
100  Make it closer to 0 if you get too few words in each line, or make it closer to 100 if there are too many excess words in each line.
101
102- `sim_threshold`
103
104  Similarity threshold for subtitle lines. Subtitle lines with larger [Levenshtein](https://en.wikipedia.org/wiki/Levenshtein_distance) ratios than this threshold will be merged together. The default value `90` is fine for most cases.
105
106  Make it closer to 0 if you get too many duplicated subtitle lines, or make it closer to 100 if you get too few subtitle lines.
107
108- `time_start` and `time_end`
109
110  Extract subtitles from only a clip of the video. The subtitle timestamps are still calculated according to the full video length.
111
112- `use_fullframe`
113
114  By default, only the bottom half of each frame is used for OCR. You can explicitly use the full frame if your subtitles are not within the bottom half of each frame.