https://github.com/ecdye/macsubtitleocr
Convert bitmap subtitles into SubRip format using the macOS Vision framework
https://github.com/ecdye/macsubtitleocr
collaborate macos ocr subtitles swift
Last synced: about 1 year ago
JSON representation
Convert bitmap subtitles into SubRip format using the macOS Vision framework
- Host: GitHub
- URL: https://github.com/ecdye/macsubtitleocr
- Owner: ecdye
- License: mit
- Created: 2024-09-02T18:19:20.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-10-24T04:46:09.000Z (over 1 year ago)
- Last Synced: 2024-10-24T11:25:13.024Z (over 1 year ago)
- Topics: collaborate, macos, ocr, subtitles, swift
- Language: Swift
- Homepage:
- Size: 600 KB
- Stars: 9
- Watchers: 3
- Forks: 1
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project
README
# macSubtitleOCR
[](https://github.com/ecdye/macSubtitleOCR/blob/main/LICENSE.md)
[](https://github.com/ecdye/macSubtitleOCR/actions/workflows/codeql.yml)
[](https://github.com/ecdye/macSubtitleOCR/actions/workflows/test.yml)
[](https://github.com/ecdye/macSubtitleOCR/actions/workflows/lint.yml)
## Overview
**macSubtitleOCR** converts bitmap subtitles into the SubRip subtitle format (SRT) using the macOS Vision framework to perform OCR.
Currently PGS and VobSub subtitles are supported.
For more details on OCR accuracy, refer to the [Accuracy](#accuracy) section below.
[Release](https://github.com/ecdye/macSubtitleOCR/releases/latest) and [Nightly](https://github.com/ecdye/macSubtitleOCR/releases/tag/nightly) builds are provided for `arm64`.
Unfortunately, GitHub Actions doesn't provide a runner I can build `x86_64` binaries on, sorry.
However, you should be able to compile for `x86_64` on you own machine by following the directions in the [Building the Project](#building-the-project) section below.
### Features
- Export raw JSON output from Vision for further analysis
- Save `.png` images of subtitles for manual correction of OCR output
- Optional support for FFmpeg in case of any issues with internal decoder
### Supported Formats
- PGS (`.mkv`, `.sup`)
- VobSub (`.mkv`, `.sub`, `.idx`)
## Building the Project
> [!IMPORTANT]
> macSubtitleOCR requires Swift 6 support to compile
To make and install the project, follow the directions below:
### Build Internal Decoder Only
To build macSubtitleOCR, follow these steps:
``` shell
git clone https://github.com/ecdye/macSubtitleOCR
cd macSubtitleOCR
swift build --configuration release
```
### Build With FFmpeg Decoder
To build with FFmpeg support, follow these steps:
``` shell
brew install ffmpeg
git clone https://github.com/ecdye/macSubtitleOCR
cd macSubtitleOCR
USE_FFMPEG=1 swift build --configuration release -Xswiftc -DFFMPEG
```
## Running Tests
The testing process compares OCR output against known correct results.
Tests aim for at least 95% accuracy, as there are slight differences in Vision results between machines.
``` shell
swift test
```
## Accuracy
In general, Vision produces a highly accurate output for almost all subtitles.
If you find an edge case with degraded performance, open an issue so it can be investigated.
In tests comparing Vision's output with [Tesseract](https://github.com/tesseract-ocr/tesseract), Vision consistently gave better results, particularly with tricky cases like properly recognizing `I`.
While some tools, like [SubtitleEdit](https://github.com/SubtitleEdit/subtitleedit), may use binary image compare for marginally better accuracy, Vision offers more flexibility with built-in language support.
## Contribution and TODO
For information on how to contribute to the project, please refer to [CONTRIBUTING.md](CONTRIBUTING.md).
If you're interested in working on specific features or improvements, check out issues tagged as [enhancements](https://github.com/ecdye/macSubtitleOCR/issues?q=is%3Aissue+is%3Aopen+label%3Aenhancement).
## References
- [Presentation Graphic Stream (PGS) Files](https://blog.thescorpius.com/index.php/2017/07/15/presentation-graphic-stream-sup-files-bluray-subtitle-format/)
- [DVD Subtitle Stream (VobSub) Files](http://www.mpucoder.com/DVD/index.html)
- [Matroska Technical Specifications](https://www.matroska.org/technical/elements.html)