pykara 0.0.1__tar.gz

pykara-0.0.1/.editorconfig

@@ -0,0 +1,4 @@
+root = true
+
+[tests/fixtures/**/*.ass]
+trim_trailing_whitespace = false

pykara-0.0.1/.gitattributes

@@ -0,0 +1,2 @@
+# ASS fixtures may include significant trailing spaces in dialogue text.
+tests/fixtures/**/*.ass whitespace=-trailing-space

pykara-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,103 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+env:
+  PYTHON_VERSION: "3.11"
+
+jobs:
+  quality:
+    name: Quality
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+          cache: "pip"
+
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            libcairo2-dev \
+            libgirepository-2.0-dev \
+            gir1.2-pango-1.0 \
+            pkg-config
+
+      - name: Install Python dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install .[dev]
+
+      - name: Run Ruff
+        run: python -m ruff check src tests
+
+      - name: Generate Pyright CI config
+        run: |
+          python - <<'PY'
+          import json
+          import site
+
+          config = {
+              "include": ["src", "tests"],
+              "typeCheckingMode": "strict",
+              "pythonVersion": "3.11",
+              "extraPaths": [".", "src", site.getsitepackages()[0]],
+              "executionEnvironments": [
+                  {
+                      "root": "tests",
+                      "reportUnknownMemberType": "none",
+                  }
+              ],
+          }
+
+          with open("pyright-ci.json", "w", encoding="utf-8") as file:
+              json.dump(config, file, indent=2)
+          PY
+
+      - name: Run Pyright
+        run: python -m pyright -p pyright-ci.json
+
+      - name: Run Rumdl
+        run: rumdl check README.md $(find docs -name '*.md' -type f | sort)
+
+  tests:
+    name: Tests
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+          cache: "pip"
+
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            libcairo2-dev \
+            libgirepository-2.0-dev \
+            gir1.2-pango-1.0 \
+            pkg-config
+
+      - name: Install Python dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install .[dev]
+
+      - name: Run Pytest
+        run: python -m pytest

pykara-0.0.1/.github/workflows/package.yml

@@ -0,0 +1,46 @@
+name: Package
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+env:
+  PYTHON_VERSION: "3.11"
+
+jobs:
+  build-distributions:
+    name: Build distributions
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+          cache: "pip"
+
+      - name: Install packaging tools
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build twine
+
+      - name: Build wheel and sdist
+        run: python -m build
+
+      - name: Check distribution metadata
+        run: python -m twine check --strict dist/*
+
+      - name: Store distribution packages
+        uses: actions/upload-artifact@v5
+        with:
+          name: python-package-distributions
+          path: dist/

pykara-0.0.1/.github/workflows/publish.yml

@@ -0,0 +1,70 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+      - "*.*.*"
+
+permissions:
+  contents: read
+
+env:
+  PYTHON_VERSION: "3.11"
+  PYPI_PACKAGE_NAME: "pykara"
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+          cache: "pip"
+
+      - name: Install packaging tools
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build twine
+
+      - name: Build wheel and sdist
+        run: python -m build
+
+      - name: Check distribution metadata
+        run: python -m twine check --strict dist/*
+
+      - name: Store distribution packages
+        uses: actions/upload-artifact@v5
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-to-pypi:
+    name: Publish to PyPI
+    if: startsWith(github.ref, 'refs/tags/')
+    needs:
+      - build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/${{ env.PYPI_PACKAGE_NAME }}
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download distribution packages
+        uses: actions/download-artifact@v6
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish distribution
+        uses: pypa/gh-action-pypi-publish@release/v1

pykara-0.0.1/.gitignore

@@ -0,0 +1,36 @@
+# Python bytecode and caches
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+
+# Virtual environments
+.venv/
+venv/
+impl/.venv/
+
+# Packaging artifacts
+build/
+dist/
+*.egg-info/
+.eggs/
+pip-wheel-metadata/
+
+# Test and lint caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.pyright/
+.pyrightcache/
+.coverage
+.coverage.*
+htmlcov/
+.rumdl_cache/
+
+# Local tooling and editor files
+.DS_Store
+.idea/
+.vscode/
+.codex
+.claude
+.agents

pykara-0.0.1/.rumdl.toml

@@ -0,0 +1,7 @@
+line-length = 88
+
+[MD013]
+line-length = 88
+code-blocks = false
+tables = false
+reflow = true

pykara-0.0.1/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: pykara
+Version: 0.0.1
+Summary: Standalone Python CLI karaoke templater.
+Project-URL: Homepage, https://github.com/pandafansub/pykara
+Project-URL: Documentation, https://github.com/pandafansub/pykara/blob/main/docs/index.md
+Project-URL: Repository, https://github.com/pandafansub/pykara
+Project-URL: Issues, https://github.com/pandafansub/pykara/issues
+Author-email: Panda Fansub <contato@pandafansub.com>
+Keywords: aegisub,ass,karaoke,subtitles
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Text Processing
+Requires-Python: >=3.11
+Requires-Dist: pycairo
+Requires-Dist: pygobject
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: coverage; extra == 'dev'
+Requires-Dist: pyright; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: rumdl; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pykara
+
+Standalone Python CLI karaoke templater for ASS subtitles.
+
+## Requirements
+
+- Python 3.11+
+- Cairo and Pango bindings available to Python
+
+On Ubuntu/Debian, the CI setup installs:
+
+```bash
+sudo apt-get install -y \
+  libcairo2-dev \
+  libgirepository-2.0-dev \
+  gir1.2-pango-1.0 \
+  pkg-config
+```
+
+## Install
+
+Install from PyPI:
+
+```bash
+python -m pip install pykara
+```
+
+The package name on PyPI is `pykara`. The CLI command remains
+`pykara`.
+
+For a source checkout with development tools:
+
+```bash
+python -m pip install -e .[dev]
+```
+
+## Documentation
+
+Start with the
+[documentation index](https://github.com/pandafansub/pykara/blob/main/docs/index.md)
+for directives, scopes, and helpers.
+
+## CLI
+
+Write a new `.ass` output file:
+
+```bash
+pykara input.ass output.ass
+```
+
+Print only the generated ASS event rows:
+
+```bash
+pykara --emit-events input.ass
+```
+
+Use timecodes for frame-baked motion:
+
+```bash
+pykara --timecodes path/to/timecodes.txt input.ass output.ass
+```
+
+Useful flags:
+
+- `--seed`: deterministic RNG seed for reproducible output
+- `--debug`: show the full traceback instead of the short CLI error
+
+## Aegisub Bridge
+
+The repository includes an Aegisub automation script at
+`bridge/pykara.lua`.
+
+The bridge expects the `pykara` command to be available in `PATH`, runs
+`pykara --emit-events` for the currently open subtitle file, removes existing
+`fx` lines, inserts the regenerated ones, and comments the source karaoke
+lines.

pykara-0.0.1/README.md

@@ -0,0 +1,76 @@
+# pykara
+
+Standalone Python CLI karaoke templater for ASS subtitles.
+
+## Requirements
+
+- Python 3.11+
+- Cairo and Pango bindings available to Python
+
+On Ubuntu/Debian, the CI setup installs:
+
+```bash
+sudo apt-get install -y \
+  libcairo2-dev \
+  libgirepository-2.0-dev \
+  gir1.2-pango-1.0 \
+  pkg-config
+```
+
+## Install
+
+Install from PyPI:
+
+```bash
+python -m pip install pykara
+```
+
+The package name on PyPI is `pykara`. The CLI command remains
+`pykara`.
+
+For a source checkout with development tools:
+
+```bash
+python -m pip install -e .[dev]
+```
+
+## Documentation
+
+Start with the
+[documentation index](https://github.com/pandafansub/pykara/blob/main/docs/index.md)
+for directives, scopes, and helpers.
+
+## CLI
+
+Write a new `.ass` output file:
+
+```bash
+pykara input.ass output.ass
+```
+
+Print only the generated ASS event rows:
+
+```bash
+pykara --emit-events input.ass
+```
+
+Use timecodes for frame-baked motion:
+
+```bash
+pykara --timecodes path/to/timecodes.txt input.ass output.ass
+```
+
+Useful flags:
+
+- `--seed`: deterministic RNG seed for reproducible output
+- `--debug`: show the full traceback instead of the short CLI error
+
+## Aegisub Bridge
+
+The repository includes an Aegisub automation script at
+`bridge/pykara.lua`.
+
+The bridge expects the `pykara` command to be available in `PATH`, runs
+`pykara --emit-events` for the currently open subtitle file, removes existing
+`fx` lines, inserts the regenerated ones, and comments the source karaoke
+lines.

pykara-0.0.1/bridge/pykara.lua

@@ -0,0 +1,243 @@
+script_name = "pykara Bridge"
+script_description = "Run pykara and insert generated FX lines"
+script_author = "pykara"
+script_version = "1.0"
+
+local function is_windows()
+    return package.config:sub(1, 1) == "\\"
+end
+
+local function shell_quote(value)
+    if is_windows() then
+        return '"' .. tostring(value):gsub('"', '""') .. '"'
+    end
+    return "'" .. tostring(value):gsub("'", "'\\''") .. "'"
+end
+
+local function join_path(...)
+    local separator = is_windows() and "\\" or "/"
+    local parts = {...}
+    return table.concat(parts, separator)
+end
+
+local function parse_ass_time(value)
+    local hours, minutes, seconds, centiseconds =
+        value:match("^(%d+):(%d%d):(%d%d)%.(%d%d)$")
+    if not hours then
+        error("Invalid ASS time: " .. tostring(value))
+    end
+    return (
+        (((tonumber(hours) * 60) + tonumber(minutes)) * 60 + tonumber(seconds))
+        * 1000
+    ) + tonumber(centiseconds) * 10
+end
+
+local function split_event_fields(value)
+    local fields = {}
+    local rest = value
+    for _ = 1, 9 do
+        local current, next_rest = rest:match("^([^,]*),(.*)$")
+        if not current then
+            break
+        end
+        table.insert(fields, current)
+        rest = next_rest
+    end
+    table.insert(fields, rest)
+    return fields
+end
+
+local function parse_generated_line(raw_line)
+    local kind, body = raw_line:match("^(%a+):%s*(.*)$")
+    if kind ~= "Dialogue" and kind ~= "Comment" then
+        error("Unexpected generated event line: " .. tostring(raw_line))
+    end
+
+    local fields = split_event_fields(body)
+    return {
+        class = "dialogue",
+        section = "[Events]",
+        comment = kind == "Comment",
+        layer = tonumber(fields[1]) or 0,
+        start_time = parse_ass_time(fields[2] or "0:00:00.00"),
+        end_time = parse_ass_time(fields[3] or "0:00:00.00"),
+        style = fields[4] or "",
+        actor = fields[5] or "",
+        margin_l = tonumber(fields[6]) or 0,
+        margin_r = tonumber(fields[7]) or 0,
+        margin_t = tonumber(fields[8]) or 0,
+        margin_b = tonumber(fields[8]) or 0,
+        effect = fields[9] or "",
+        text = fields[10] or "",
+        raw = raw_line,
+    }
+end
+
+local function current_ass_path()
+    local dir = aegisub.decode_path("?script")
+    local name = aegisub.file_name()
+
+    if not dir or dir == "" or not name or name == "" then
+        return nil
+    end
+
+    return join_path(dir, name)
+end
+
+local function pykara_command()
+    return "pykara --emit-events "
+end
+
+local function show_text_dialog(text)
+    aegisub.dialog.display({
+        {
+            class = "textbox",
+            x = 0,
+            y = 0,
+            width = 60,
+            height = 10,
+            text = text,
+        }
+    }, {"OK"})
+end
+
+local function show_missing_pykara_message(output)
+    local message = table.concat({
+        "The `pykara` command is not available in PATH.",
+        "",
+        "Install it in your environment and ensure the command is available.",
+        "",
+        "Command output:",
+        output,
+    }, "\n")
+    show_text_dialog(message)
+end
+
+local function strip_ansi(text)
+    return (text or ""):gsub("\27%[[%d;]*m", "")
+end
+
+local function normalize_output_lines(output)
+    local cleaned = strip_ansi(output)
+    local lines = {}
+    for raw_line in cleaned:gmatch("[^\r\n]+") do
+        local line = raw_line:gsub("%s+$", "")
+        if line ~= "" then
+            table.insert(lines, line)
+        end
+    end
+    return lines
+end
+
+local function try_bridge_command(command)
+    local pipe = io.popen(command .. " 2>&1")
+
+    if not pipe then
+        return false, "io.popen failed in this Aegisub build.", false
+    end
+
+    local output = pipe:read("*a") or ""
+    local ok = pipe:close()
+
+    return ok ~= nil, output, true
+end
+
+local function remove_existing_fx_lines(subs)
+    for i = #subs, 1, -1 do
+        local line = subs[i]
+        if line.class == "dialogue" and not line.comment and line.effect == "fx" then
+            subs.delete(i)
+        end
+    end
+end
+
+local function comment_input_lines(subs)
+    for i = 1, #subs do
+        local line = subs[i]
+        if line.class == "dialogue" and not line.comment then
+            local effect = (line.effect or ""):lower()
+            if effect == "kara" or effect == "karaoke" then
+                line.comment = true
+                subs[i] = line
+            end
+        end
+    end
+end
+
+local function run_bridge(subs)
+    local input_path = current_ass_path()
+
+    if not input_path then
+        aegisub.dialog.display({
+            {
+                class = "label",
+                x = 0,
+                y = 0,
+                width = 60,
+                height = 2,
+                label = "Could not resolve the current subtitle path.",
+            }
+        }, {"OK"})
+        return
+    end
+
+    local command = pykara_command() .. shell_quote(input_path)
+    local succeeded, output, command_started = try_bridge_command(command)
+
+    if not command_started then
+        aegisub.dialog.display({
+            {
+                class = "label",
+                x = 0,
+                y = 0,
+                width = 60,
+                height = 2,
+                label = "io.popen failed in this Aegisub build.",
+            }
+        }, {"OK"})
+        return
+    end
+
+    if not succeeded then
+        if output:match("command not found")
+            or output:match("not found")
+            or output:match("is not recognized as an internal or external command")
+        then
+            show_missing_pykara_message(output)
+            return
+        end
+
+        if output:match("No module named ['\"]pykara['\"]")
+            or output:match("ModuleNotFoundError:.-pykara")
+        then
+            show_missing_pykara_message(output)
+            return
+        end
+
+        local lines = normalize_output_lines(output)
+        if #lines > 0 then
+            show_text_dialog(table.concat(lines, "\n"))
+        else
+            show_text_dialog(output)
+        end
+        return
+    end
+
+    remove_existing_fx_lines(subs)
+
+    for raw_line in output:gmatch("[^\r\n]+") do
+        if raw_line:match("^Dialogue: ") or raw_line:match("^Comment: ") then
+            subs.append(parse_generated_line(raw_line))
+        end
+    end
+
+    comment_input_lines(subs)
+
+    aegisub.set_undo_point("pykara Apply Templates")
+end
+
+aegisub.register_macro(
+    "pykara Apply Templates",
+    "Generate FX lines through the Python bridge",
+    run_bridge
+)