videocr/README.md

112 lines
3.7 KiB
Markdown
Raw Normal View History

2019-04-29 04:14:35 +02:00
# videocr
2019-04-30 17:59:10 +02:00
Extract hardcoded (burned-in) subtitles from videos using the [Tesseract](https://github.com/tesseract-ocr/tesseract) OCR engine with Python.
2019-04-29 04:14:35 +02:00
2019-04-29 23:16:37 +02:00
Input a video with hardcoded subtitles:
2019-04-29 04:14:35 +02:00
2019-04-29 05:00:25 +02:00
<p float="left">
<img width="430" alt="screenshot" src="https://user-images.githubusercontent.com/10210967/56873658-3b76dd00-6a34-11e9-95c6-cd6edc721f58.png">
<img width="430" alt="screenshot" src="https://user-images.githubusercontent.com/10210967/56873659-3b76dd00-6a34-11e9-97aa-2c3e96fe3a97.png">
</p>
2019-04-29 04:14:35 +02:00
2019-04-29 05:00:25 +02:00
```python
2019-12-15 15:44:55 +01:00
# example.py
2019-04-30 17:59:10 +02:00
2019-12-15 15:44:55 +01:00
from videocr import get_subtitles
2019-04-29 04:14:35 +02:00
2019-12-15 15:44:55 +01:00
if __name__ == '__main__': # This check is mandatory for Windows.
print(get_subtitles('video.mp4', lang='chi_sim+eng', sim_threshold=70, conf_threshold=65))
2019-04-29 04:14:35 +02:00
```
2019-12-15 15:44:55 +01:00
`$ python3 example.py`
2019-04-30 17:59:10 +02:00
2019-04-29 04:14:35 +02:00
Output:
```
0
2019-04-29 23:16:37 +02:00
00:00:01,042 --> 00:00:02,877
喝 点 什么 ?
What can I get you?
2019-04-29 04:14:35 +02:00
1
2019-04-29 23:16:37 +02:00
00:00:03,044 --> 00:00:05,463
我 不 知道
Um, I'm not sure.
2019-04-29 04:14:35 +02:00
2
2019-04-29 23:16:37 +02:00
00:00:08,091 --> 00:00:10,635
2019-04-29 04:14:35 +02:00
休闲 时 光 …
For relaxing times, make it...
3
2019-04-29 23:16:37 +02:00
00:00:10,677 --> 00:00:12,595
2019-04-29 04:14:35 +02:00
三 得 利 时 光
Bartender, Bob Suntory time.
4
2019-04-29 23:16:37 +02:00
00:00:14,472 --> 00:00:17,142
我 要 一 杯 伏特 加
2019-04-29 04:14:35 +02:00
Un, I'll have a vodka tonic.
5
2019-04-29 23:16:37 +02:00
00:00:18,059 --> 00:00:19,019
2019-04-29 04:14:35 +02:00
谢谢
Laughs Thanks.
```
2019-04-29 05:00:25 +02:00
2019-04-29 23:16:37 +02:00
## Performance
2019-05-17 17:46:43 +02:00
The 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.
2019-04-29 23:16:37 +02:00
2019-04-30 03:00:17 +02:00
## Installation
1. Install [Tesseract](https://github.com/tesseract-ocr/tesseract/wiki) and make sure it is in your `$PATH`
2. `$ pip install videocr`
2019-12-15 15:44:55 +01:00
## API
1. Return subtitle string in SRT format
```python
get_subtitles(
video_path: str, lang='eng', time_start='0:00', time_end='',
conf_threshold=65, sim_threshold=90, use_fullframe=False)
```
2. Write subtitles to `file_path`
```python
save_subtitles_to_file(
video_path: str, file_path='subtitle.srt', lang='eng', time_start='0:00', time_end='',
conf_threshold=65, sim_threshold=90, use_fullframe=False)
```
2019-04-29 05:00:25 +02:00
2019-04-29 17:02:35 +02:00
### Parameters
2019-04-29 05:00:25 +02:00
- `lang`
2019-04-30 17:59:10 +02:00
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.
2019-04-29 23:16:37 +02:00
2019-05-17 17:46:43 +02:00
Note that you can use more than one language, e.g. `lang='hin+eng'` for Hindi and English together.
2019-04-29 23:16:37 +02:00
2019-05-17 17:46:43 +02:00
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).
2019-04-29 05:00:25 +02:00
- `conf_threshold`
2019-05-17 17:46:43 +02:00
Confidence threshold for word predictions. Words with lower confidence than this value will be discarded. The default value `65` is fine for most cases.
2019-04-29 05:00:25 +02:00
2019-05-17 17:46:43 +02:00
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.
2019-04-29 05:00:25 +02:00
- `sim_threshold`
2019-05-17 17:46:43 +02:00
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.
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.
- `time_start` and `time_end`
2019-04-29 05:00:25 +02:00
2019-05-17 17:46:43 +02:00
Extract subtitles from only a clip of the video. The subtitle timestamps are still calculated according to the full video length.
2019-04-29 05:00:25 +02:00
- `use_fullframe`
2019-04-29 17:02:35 +02:00
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.