tvsub-mcp 0.1.0__tar.gz

tvsub_mcp-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Youngji Kim
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

tvsub_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: tvsub-mcp
+Version: 0.1.0
+Summary: MCP companion for the tvsub subtitle overlay on Apple TV.app for macOS
+License-Expression: MIT
+Project-URL: Homepage, https://youngji.kim/tvsub
+Project-URL: Repository, https://github.com/launzi/tvsub-mcp
+Project-URL: Issues, https://github.com/launzi/tvsub-mcp/issues
+Keywords: mcp,subtitles,macos,apple-tv
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: MacOS X
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp<2,>=1.2
+Requires-Dist: anthropic<1,>=0.117
+Dynamic: license-file
+
+# tvsub MCP
+
+<!-- mcp-name: io.github.launzi/tvsub-mcp -->
+
+`tvsub-mcp` is the MCP companion for [tvsub](https://youngji.kim/tvsub), an
+experimental subtitle overlay for Apple TV.app on macOS. It lets an MCP client
+inspect the current playback item, choose or translate a subtitle file, adjust
+its appearance, start or stop the overlay, and calibrate subtitle timing.
+
+The server does not download subtitles, bypass DRM, modify video, or launch
+TV.app. You provide subtitle files that you have the right to use and start
+playback yourself.
+
+## Requirements
+
+- macOS
+- [tvsub](https://youngji.kim/tvsub), installed and built
+- Python 3.12 or later
+- [`uv`](https://docs.astral.sh/uv/getting-started/installation/) for the
+  recommended `uvx` installation
+- An Anthropic API key only if you use subtitle translation
+
+## Install and register with Claude Code
+
+Replace `/absolute/path/to/tvsub` with the directory containing tvsub's
+`build/`, `config/`, `src/`, and `subtitles/` directories.
+
+```bash
+brew install uv
+
+claude mcp add --transport stdio --scope user tvsub -- \
+  uvx tvsub-mcp==0.1.0 \
+  --tvsub-root /absolute/path/to/tvsub
+
+claude mcp get tvsub
+claude mcp list
+```
+
+To enable translation, export your key and include it when registering the
+server. The key is not needed for any other tool.
+
+```bash
+export ANTHROPIC_API_KEY="your-key"
+
+claude mcp add --transport stdio --scope user \
+  --env ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
+  tvsub -- uvx tvsub-mcp==0.1.0 \
+  --tvsub-root /absolute/path/to/tvsub
+```
+
+Other stdio MCP clients can launch the same command:
+
+```bash
+uvx tvsub-mcp==0.1.0 --tvsub-root /absolute/path/to/tvsub
+```
+
+## Tools
+
+| Tool | Purpose |
+| --- | --- |
+| `now_playing` | Read the current Apple TV.app title, content ID, position, and playback state. |
+| `list_subtitles` | List and parse SRT, SMI, SAMI, and VTT files in tvsub's subtitle library. |
+| `load_subtitle` | Select a subtitle file for the current content while preserving sync anchors by default. |
+| `translate_subtitle` | Estimate or perform an LLM translation with cue and timecode validation. |
+| `list_fonts` | List installed macOS fonts and check sample glyph coverage. |
+| `set_style` | Change font, size, colors, outline, background, and screen position. |
+| `start_overlay` | Start tvsub with the selected subtitle and style. |
+| `stop_overlay` | Stop only the overlay process started by this server. |
+| `calibrate_sync` | Store one or more dialogue anchors and calculate timing offset and drift. |
+| `status` | Summarize playback, overlay, subtitle, style, and calibration state. |
+
+Before translating, call `translate_subtitle` with `dry_run=true` to review the
+cue count, batch count, and estimated cost.
+
+## Important notices
+
+- **Experimental software:** expect rough edges and breaking changes. Keep a
+  backup of your tvsub configuration and subtitle files.
+- **Data sent to Anthropic:** translation sends the selected subtitle text and
+  surrounding subtitle context to the Anthropic API. Loading, styling, sync,
+  and overlay controls do not send subtitle text to Anthropic.
+- **User-paid API usage:** translation uses your Anthropic API key. All API
+  charges are your responsibility; estimates can differ from the final bill.
+- **Private API risk:** tvsub reads Apple playback state through undocumented
+  macOS MediaRemote interfaces. Apple does not support this integration and a
+  macOS update may change or disable it.
+- **Content rights:** you are responsible for having the right to process and
+  translate subtitle files. Do not redistribute protected content without
+  permission.
+- This project is independent from and not affiliated with Apple or Anthropic.
+
+## Development
+
+```bash
+python3.12 -m venv .venv
+.venv/bin/python -m pip install -e .
+.venv/bin/python -m unittest discover -s tests -p 'test_*.py' -v
+TVSUB_TEST_PYTHON="$PWD/.venv/bin/python" .venv/bin/python tests/stdio_smoke.py
+bash scripts/hygiene-check.sh
+```
+
+Linux can run the unit tests and mock stdio smoke test. Apple TV.app,
+MediaRemote, CoreText, and the real overlay require macOS.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+

tvsub_mcp-0.1.0/README.md

@@ -0,0 +1,108 @@
+# tvsub MCP
+
+<!-- mcp-name: io.github.launzi/tvsub-mcp -->
+
+`tvsub-mcp` is the MCP companion for [tvsub](https://youngji.kim/tvsub), an
+experimental subtitle overlay for Apple TV.app on macOS. It lets an MCP client
+inspect the current playback item, choose or translate a subtitle file, adjust
+its appearance, start or stop the overlay, and calibrate subtitle timing.
+
+The server does not download subtitles, bypass DRM, modify video, or launch
+TV.app. You provide subtitle files that you have the right to use and start
+playback yourself.
+
+## Requirements
+
+- macOS
+- [tvsub](https://youngji.kim/tvsub), installed and built
+- Python 3.12 or later
+- [`uv`](https://docs.astral.sh/uv/getting-started/installation/) for the
+  recommended `uvx` installation
+- An Anthropic API key only if you use subtitle translation
+
+## Install and register with Claude Code
+
+Replace `/absolute/path/to/tvsub` with the directory containing tvsub's
+`build/`, `config/`, `src/`, and `subtitles/` directories.
+
+```bash
+brew install uv
+
+claude mcp add --transport stdio --scope user tvsub -- \
+  uvx tvsub-mcp==0.1.0 \
+  --tvsub-root /absolute/path/to/tvsub
+
+claude mcp get tvsub
+claude mcp list
+```
+
+To enable translation, export your key and include it when registering the
+server. The key is not needed for any other tool.
+
+```bash
+export ANTHROPIC_API_KEY="your-key"
+
+claude mcp add --transport stdio --scope user \
+  --env ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
+  tvsub -- uvx tvsub-mcp==0.1.0 \
+  --tvsub-root /absolute/path/to/tvsub
+```
+
+Other stdio MCP clients can launch the same command:
+
+```bash
+uvx tvsub-mcp==0.1.0 --tvsub-root /absolute/path/to/tvsub
+```
+
+## Tools
+
+| Tool | Purpose |
+| --- | --- |
+| `now_playing` | Read the current Apple TV.app title, content ID, position, and playback state. |
+| `list_subtitles` | List and parse SRT, SMI, SAMI, and VTT files in tvsub's subtitle library. |
+| `load_subtitle` | Select a subtitle file for the current content while preserving sync anchors by default. |
+| `translate_subtitle` | Estimate or perform an LLM translation with cue and timecode validation. |
+| `list_fonts` | List installed macOS fonts and check sample glyph coverage. |
+| `set_style` | Change font, size, colors, outline, background, and screen position. |
+| `start_overlay` | Start tvsub with the selected subtitle and style. |
+| `stop_overlay` | Stop only the overlay process started by this server. |
+| `calibrate_sync` | Store one or more dialogue anchors and calculate timing offset and drift. |
+| `status` | Summarize playback, overlay, subtitle, style, and calibration state. |
+
+Before translating, call `translate_subtitle` with `dry_run=true` to review the
+cue count, batch count, and estimated cost.
+
+## Important notices
+
+- **Experimental software:** expect rough edges and breaking changes. Keep a
+  backup of your tvsub configuration and subtitle files.
+- **Data sent to Anthropic:** translation sends the selected subtitle text and
+  surrounding subtitle context to the Anthropic API. Loading, styling, sync,
+  and overlay controls do not send subtitle text to Anthropic.
+- **User-paid API usage:** translation uses your Anthropic API key. All API
+  charges are your responsibility; estimates can differ from the final bill.
+- **Private API risk:** tvsub reads Apple playback state through undocumented
+  macOS MediaRemote interfaces. Apple does not support this integration and a
+  macOS update may change or disable it.
+- **Content rights:** you are responsible for having the right to process and
+  translate subtitle files. Do not redistribute protected content without
+  permission.
+- This project is independent from and not affiliated with Apple or Anthropic.
+
+## Development
+
+```bash
+python3.12 -m venv .venv
+.venv/bin/python -m pip install -e .
+.venv/bin/python -m unittest discover -s tests -p 'test_*.py' -v
+TVSUB_TEST_PYTHON="$PWD/.venv/bin/python" .venv/bin/python tests/stdio_smoke.py
+bash scripts/hygiene-check.sh
+```
+
+Linux can run the unit tests and mock stdio smoke test. Apple TV.app,
+MediaRemote, CoreText, and the real overlay require macOS.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+

tvsub_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tvsub-mcp"
+version = "0.1.0"
+description = "MCP companion for the tvsub subtitle overlay on Apple TV.app for macOS"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["mcp", "subtitles", "macos", "apple-tv"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: MacOS X",
+  "Operating System :: MacOS",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+  "mcp>=1.2,<2",
+  "anthropic>=0.117,<1",
+]
+
+[project.urls]
+Homepage = "https://youngji.kim/tvsub"
+Repository = "https://github.com/launzi/tvsub-mcp"
+Issues = "https://github.com/launzi/tvsub-mcp/issues"
+
+[project.scripts]
+tvsub-mcp = "tvsub_mcp.server:main"
+
+[tool.setuptools.package-data]
+tvsub_mcp = ["helpers/*.swift"]
+

tvsub_mcp-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tvsub_mcp-0.1.0/tests/test_calibration.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import unittest
+
+from tvsub_mcp.calibration import calculate
+
+
+class CalibrationTests(unittest.TestCase):
+    def test_no_anchor_is_identity(self) -> None:
+        result = calculate([])
+        self.assertEqual(result.scale, 1.0)
+        self.assertEqual(result.offset, 0.0)
+
+    def test_one_anchor_is_offset_only(self) -> None:
+        result = calculate([{"subTime": 100, "actualTime": 107.27}])
+        self.assertEqual(result.scale, 1.0)
+        self.assertAlmostEqual(result.offset, 7.27)
+
+    def test_two_anchor_pal_scale(self) -> None:
+        anchors = [
+            {"subTime": 100, "actualTime": 100 * 1.0427 + 3},
+            {"subTime": 7000, "actualTime": 7000 * 1.0427 + 3},
+        ]
+        result = calculate(anchors)
+        self.assertAlmostEqual(result.scale, 1.0427, places=6)
+        self.assertAlmostEqual(result.offset, 3.0, places=6)
+        self.assertIsNone(result.warning)
+
+    def test_close_anchors_warn(self) -> None:
+        result = calculate([
+            {"subTime": 10, "actualTime": 12},
+            {"subTime": 20, "actualTime": 22},
+        ])
+        self.assertIn("불안정", result.warning or "")
+
+
+if __name__ == "__main__":
+    unittest.main()
+

tvsub_mcp-0.1.0/tests/test_server.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import os
+import tempfile
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+from tvsub_mcp.server import _load_env
+
+
+class ServerEnvironmentTests(unittest.TestCase):
+    def test_load_env_reads_only_explicit_file_and_allowed_key(self) -> None:
+        with tempfile.TemporaryDirectory() as temp:
+            root = Path(temp)
+            explicit = root / "project" / ".env"
+            explicit.parent.mkdir()
+            explicit.write_text(
+                "ANTHROPIC_API_KEY=fixture-key\nUNRELATED_SECRET=must-not-load\n",
+                encoding="utf-8",
+            )
+            (root / ".env").write_text("ANTHROPIC_API_KEY=parent-key\n", encoding="utf-8")
+            with patch.dict(os.environ, {}, clear=True):
+                _load_env(explicit)
+                self.assertEqual(os.environ.get("ANTHROPIC_API_KEY"), "fixture-key")
+                self.assertNotIn("UNRELATED_SECRET", os.environ)
+
+    def test_load_env_does_not_search_parent_directories(self) -> None:
+        with tempfile.TemporaryDirectory() as temp:
+            root = Path(temp)
+            (root / ".env").write_text("ANTHROPIC_API_KEY=parent-key\n", encoding="utf-8")
+            missing_explicit = root / "project" / ".env"
+            with patch.dict(os.environ, {}, clear=True):
+                _load_env(missing_explicit)
+                self.assertNotIn("ANTHROPIC_API_KEY", os.environ)
+
+
+if __name__ == "__main__":
+    unittest.main()

tvsub_mcp-0.1.0/tests/test_service.py

@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+import subprocess
+import tempfile
+import unittest
+from types import SimpleNamespace
+from unittest.mock import patch
+from pathlib import Path
+
+from tvsub_mcp.service import TvsubService, should_use_applescript_position
+
+
+SRT = """1
+00:00:10,000 --> 00:00:12,000
+First line
+
+2
+00:10:00,000 --> 00:10:02,000
+Late line
+
+"""
+
+
+class ServiceTests(unittest.TestCase):
+    def test_cross_source_threshold_matches_swift_rule(self) -> None:
+        self.assertTrue(should_use_applescript_position(35.8, 300.1))
+        self.assertFalse(should_use_applescript_position(100.0, 101.999))
+        self.assertFalse(should_use_applescript_position(100.0, 102.0))
+        self.assertTrue(should_use_applescript_position(100.0, 102.001))
+
+    def test_live_now_playing_uses_tv_applescript_on_disagreement(self) -> None:
+        with tempfile.TemporaryDirectory() as temp:
+            root = Path(temp)
+            (root / "src").mkdir()
+            (root / "src" / "nowplaying.js").write_text("fixture", encoding="utf-8")
+            media_remote = SimpleNamespace(
+                returncode=0,
+                stdout=(
+                    '{"bundleID":"com.apple.TV","app":"TV",'
+                    '"kMRMediaRemoteNowPlayingInfoTitle":"Example",'
+                    '"kMRMediaRemoteNowPlayingInfoElapsedTime":35.8,'
+                    '"kMRMediaRemoteNowPlayingInfoTimestamp":0,'
+                    '"kMRMediaRemoteNowPlayingInfoPlaybackRate":1,'
+                    '"kMRMediaRemoteNowPlayingInfoDuration":1000}'
+                ),
+                stderr="",
+            )
+            service = TvsubService(root)
+            with patch("tvsub_mcp.service.platform.system", return_value="Darwin"), \
+                 patch("tvsub_mcp.service.subprocess.run", return_value=media_remote), \
+                 patch.object(service, "_tv_player_ground_truth", return_value=(300.1, "playing")):
+                playback = service.now_playing()
+            self.assertTrue(playback["sync_disagreement"])
+            self.assertEqual(playback["location_ms"], 300_100)
+            self.assertEqual(playback["media_remote_location_ms"], 35_800)
+            self.assertEqual(playback["source"], "AppleScript/TV (MediaRemote disagreement)")
+
+    def test_live_now_playing_quietly_falls_back_when_applescript_fails(self) -> None:
+        with tempfile.TemporaryDirectory() as temp:
+            root = Path(temp)
+            (root / "src").mkdir()
+            (root / "src" / "nowplaying.js").write_text("fixture", encoding="utf-8")
+            media_remote = SimpleNamespace(
+                returncode=0,
+                stdout=(
+                    '{"bundleID":"com.apple.TV",'
+                    '"kMRMediaRemoteNowPlayingInfoElapsedTime":35.8,'
+                    '"kMRMediaRemoteNowPlayingInfoTimestamp":0,'
+                    '"kMRMediaRemoteNowPlayingInfoPlaybackRate":0}'
+                ),
+                stderr="",
+            )
+            service = TvsubService(root)
+            with patch("tvsub_mcp.service.platform.system", return_value="Darwin"), \
+                 patch("tvsub_mcp.service.subprocess.run", return_value=media_remote), \
+                 patch.object(service, "_tv_player_ground_truth", side_effect=subprocess.TimeoutExpired("osascript", 2)):
+                playback = service.now_playing()
+            self.assertFalse(playback["sync_disagreement"])
+            self.assertEqual(playback["location_ms"], 35_800)
+            self.assertEqual(playback["source"], "MediaRemote/JXA")
+
+    def test_calibration_refuses_disagreeing_anchor_without_writing(self) -> None:
+        with tempfile.TemporaryDirectory() as temp:
+            root = Path(temp)
+            (root / "subtitles").mkdir()
+            (root / "subtitles" / "sample.srt").write_text(SRT, encoding="utf-8")
+            service = TvsubService(root, mock=True)
+            service.load_subtitle("sample.srt", "movie-1")
+            config_path = root / "config" / "movie-movie-1.json"
+            before = config_path.read_text(encoding="utf-8")
+            disagreement = {
+                "is_playing": False,
+                "location_ms": 300_100,
+                "sync_disagreement": True,
+                "media_remote_location_ms": 35_800,
+                "apple_script_location_ms": 300_100,
+            }
+            with patch.object(service, "now_playing", return_value=disagreement):
+                result = service.calibrate_sync("First line", store_id="movie-1")
+            self.assertFalse(result["anchor_recorded"])
+            self.assertEqual(result["reason"], "mediaremote-applescript-disagreement")
+            self.assertEqual(config_path.read_text(encoding="utf-8"), before)
+
+    def test_mock_flow_and_compatible_movie_config(self) -> None:
+        with tempfile.TemporaryDirectory() as temp:
+            root = Path(temp)
+            (root / "subtitles").mkdir()
+            (root / "subtitles" / "sample.srt").write_text(SRT, encoding="utf-8")
+            service = TvsubService(root, mock=True)
+            self.assertEqual(service.now_playing()["title"], "Example Movie (Mock)")
+            self.assertEqual(service.now_playing()["store_id"], "fixture-movie-001")
+            listed = service.list_subtitles()
+            self.assertEqual(listed["count"], 1)
+            self.assertEqual(listed["library"], "subtitles")
+            self.assertEqual(listed["subtitles"][0]["path"], "subtitles/sample.srt")
+            loaded = service.load_subtitle("sample.srt", "movie-1")
+            self.assertTrue(loaded["loaded"])
+            self.assertEqual(loaded["subtitle"]["path"], "subtitles/sample.srt")
+            first = service.calibrate_sync("First line", store_id="movie-1", actual_time=15)
+            second = service.calibrate_sync("Late line", store_id="movie-1", actual_time=620)
+            self.assertEqual(second["anchor_count"], 2)
+            config = (root / "config" / "movie-movie-1.json").read_text(encoding="utf-8")
+            self.assertIn('"subTime"', config)
+            self.assertIn('"actualTime"', config)
+            started = service.start_overlay(store_id="movie-1")
+            self.assertTrue(started["started"])
+            self.assertEqual(started["subtitle"], "subtitles/sample.srt")
+            self.assertNotIn(str(root), str(service.status()))
+            style = service.set_style(
+                font_family="Apple SD Gothic Neo", font_size=52,
+                bottom_margin=0.09, language="ko",
+            )
+            self.assertTrue(style["applies_live"])
+            self.assertEqual(style["positioning"]["reference"], "tv-video-window")
+            self.assertEqual(style["positioning"]["bottom_margin_ratio"], 0.09)
+            self.assertEqual(style["positioning"]["fallback"], "configured-screen")
+            status = service.status()
+            self.assertEqual(status["positioning"], style["positioning"])
+            self.assertEqual(status["positioning"]["screen_index_role"], "fallback-only")
+            self.assertTrue(service.stop_overlay()["stopped"])
+
+    def test_start_overlay_movie_override_does_not_bypass_tv_source_filter(self) -> None:
+        with tempfile.TemporaryDirectory() as temp:
+            root = Path(temp)
+            (root / "subtitles").mkdir()
+            (root / "subtitles" / "sample.srt").write_text(SRT, encoding="utf-8")
+            service = TvsubService(root, mock=True)
+            service.load_subtitle("sample.srt", "movie-1")
+
+            for bundle_id in ("com.apple.Music", ""):
+                with self.subTest(bundle_id=bundle_id or "missing"):
+                    with patch.dict(
+                        "os.environ",
+                        {"TVSUB_MOCK_APP": "Music", "TVSUB_MOCK_BUNDLE_ID": bundle_id},
+                    ):
+                        with self.assertRaisesRegex(RuntimeError, "소스 검사는 우회하지 않습니다"):
+                            service.start_overlay(store_id="movie-1")
+                    self.assertFalse(service.overlay_state_path.exists())
+
+    def test_missing_subtitle_error_does_not_expose_root(self) -> None:
+        with tempfile.TemporaryDirectory() as temp:
+            root = Path(temp)
+            service = TvsubService(root, mock=True)
+            with self.assertRaises(FileNotFoundError) as caught:
+                service.load_subtitle("missing.srt", "movie-1")
+            self.assertNotIn(str(root), str(caught.exception))
+            self.assertIn("subtitles/missing.srt", str(caught.exception))
+
+    def test_parse_error_does_not_expose_root(self) -> None:
+        with tempfile.TemporaryDirectory() as temp:
+            root = Path(temp)
+            (root / "subtitles").mkdir()
+            (root / "subtitles" / "broken.srt").write_text("not a subtitle", encoding="utf-8")
+            service = TvsubService(root, mock=True)
+            listed = service.list_subtitles()
+            self.assertNotIn(str(root), str(listed))
+            with self.assertRaises(ValueError) as caught:
+                service.load_subtitle("broken.srt", "movie-1")
+            self.assertNotIn(str(root), str(caught.exception))
+
+
+if __name__ == "__main__":
+    unittest.main()

tvsub_mcp-0.1.0/tests/test_subtitles.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import tempfile
+import unittest
+from pathlib import Path
+
+from tvsub_mcp.subtitles import load_subtitle, validate_timeline, write_srt
+
+
+SRT = """1
+00:00:01,000 --> 00:00:02,500
+<i>Hello</i>
+
+2
+00:01:05.25 --> 00:01:07.750
+Second line
+
+"""
+
+
+class SubtitleTests(unittest.TestCase):
+    def test_srt_preserves_timecodes_and_count(self) -> None:
+        with tempfile.TemporaryDirectory() as temp:
+            source = Path(temp) / "sample.srt"
+            output = Path(temp) / "sample.ko.srt"
+            source.write_text(SRT, encoding="utf-8")
+            document = load_subtitle(source)
+            self.assertEqual(document.encoding, "UTF-8")
+            self.assertEqual(document.format, "srt")
+            self.assertEqual(len(document.cues), 2)
+            self.assertEqual(document.cues[0].timecode, "00:00:01,000 --> 00:00:02,500")
+            self.assertEqual(document.cues[0].text, "Hello")
+            write_srt(document.cues, {1: "안녕", 2: "둘째 줄"}, output)
+            translated = load_subtitle(output)
+            validate_timeline(document, translated)
+
+    def test_cp949_smi_selects_korean_track(self) -> None:
+        smi = """<SAMI><BODY>
+<SYNC Start=1000><P Class=KRCC>첫째<br>줄
+<SYNC Start=2000><P Class=KRCC>&nbsp;
+<SYNC Start=1000><P Class=ENCC>First line
+<SYNC Start=2000><P Class=ENCC>&nbsp;
+</BODY></SAMI>"""
+        with tempfile.TemporaryDirectory() as temp:
+            source = Path(temp) / "sample.smi"
+            source.write_bytes(smi.encode("cp949"))
+            document = load_subtitle(source)
+            self.assertEqual(document.encoding, "CP949")
+            self.assertEqual(document.selected_class, "KRCC")
+            self.assertEqual(len(document.cues), 1)
+            self.assertEqual(document.cues[0].lines, ["첫째", "줄"])
+            self.assertEqual(document.cues[0].end, 2.0)
+
+
+if __name__ == "__main__":
+    unittest.main()
+

tvsub_mcp-0.1.0/tvsub_mcp/__init__.py

@@ -0,0 +1,4 @@
+"""tvsub MCP server package."""
+
+__version__ = "0.1.0"
+

tvsub_mcp-0.1.0/tvsub_mcp/calibration.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(slots=True)
+class Calibration:
+    scale: float
+    offset: float
+    warning: str | None = None
+
+
+def calculate(anchors: list[dict]) -> Calibration:
+    ordered = sorted(anchors, key=lambda item: float(item["subTime"]))
+    if not ordered:
+        return Calibration(1.0, 0.0)
+    if len(ordered) == 1:
+        return Calibration(1.0, float(ordered[0]["actualTime"]) - float(ordered[0]["subTime"]))
+    xs = [float(item["subTime"]) for item in ordered]
+    ys = [float(item["actualTime"]) for item in ordered]
+    n = len(xs)
+    sx, sy = sum(xs), sum(ys)
+    sxx = sum(value * value for value in xs)
+    sxy = sum(x * y for x, y in zip(xs, ys))
+    denominator = n * sxx - sx * sx
+    if abs(denominator) < 1e-9:
+        scale = 1.0
+        offset = ys[0] - xs[0]
+    else:
+        scale = (n * sxy - sx * sy) / denominator
+        offset = (sy - scale * sx) / n
+    span = max(xs) - min(xs)
+    warning = None
+    if span < 300:
+        warning = f"앵커 간격이 {span:.0f}초뿐이라 scale 추정이 불안정합니다."
+    elif scale < 0.9 or scale > 1.15:
+        warning = f"scale={scale:.4f}가 정상 범위(0.9~1.15)를 벗어났습니다."
+    return Calibration(scale, offset, warning)
+