songscan 0.1.0__tar.gz

songscan-0.1.0/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: songscan
+Version: 0.1.0
+Summary: Read songs out of PDFs: chord charts as ChordPro, sheet music as MusicXML
+Author: Jared McKnight
+Author-email: Jared McKnight <jmcknight@archertech.ca>
+License-Expression: MIT
+Requires-Dist: anthropic
+Requires-Dist: chordpro-renderer
+Requires-Dist: pdfplumber
+Requires-Dist: pydantic>=2
+Requires-Python: >=3.13
+Project-URL: Homepage, https://github.com/jnhmcknight/songscan
+Project-URL: Repository, https://github.com/jnhmcknight/songscan
+Project-URL: Issues, https://github.com/jnhmcknight/songscan/issues
+Description-Content-Type: text/markdown
+
+# songscan
+
+Read songs out of PDFs. A chord chart becomes [ChordPro](https://www.chordpro.org/), with the
+song's details (title, artists, key, tempo, time, capo, copyright) alongside; sheet music will
+become MusicXML.
+
+A PDF's own text is read first: charts typed up in a word processor or chart app keep their words
+and where each sits on the page, so their chords can be put back over the syllables they are
+played on, without asking anyone. Anything else (scans, photos, sheet music, or text that isn't
+plainly a chord chart) is read by Claude, looking at its pages.
+
+## Installation
+
+```bash
+uv add "songscan @ git+https://github.com/jnhmcknight/songscan.git"
+```
+
+Reading scans needs an [Anthropic API key](https://platform.claude.com/), in `ANTHROPIC_API_KEY`
+or a client you pass in. PDFs with their own text don't use it.
+
+## Usage
+
+```python
+from songscan import ScanError, scan_pdf
+
+try:
+    result = scan_pdf(pdf_bytes)
+except ScanError as error:
+    ...  # error.retryable: whether trying again later may work
+
+result.kind       # "chord_chart", "score" or "other"
+result.chordpro   # a chord chart's ChordPro, details and all; else None
+result.meta       # ScanMeta: title, artists, key, tempo, time, capo, copyright
+result.source     # "text" (the PDF's own) or "vision" (Claude's reading)
+result.warnings   # anything to check, or that couldn't be done
+```
+
+To choose the client or model:
+
+```python
+import anthropic
+
+result = scan_pdf(pdf_bytes, client=anthropic.Anthropic(api_key=...), model="claude-opus-5-5")
+```
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check && uv run black --check . && uv run pyright
+```
+
+Tests that read PDFs with vision use a stand-in for Claude. To run them against the real API
+instead (which costs a little), set `SONGSCAN_LIVE_API=1` with a key in `ANTHROPIC_API_KEY`:
+
+```bash
+SONGSCAN_LIVE_API=1 uv run pytest
+```
+
+Tests of how songscan handles the API's answers and errors use the stand-in either way.

songscan-0.1.0/README.md

@@ -0,0 +1,61 @@
+# songscan
+
+Read songs out of PDFs. A chord chart becomes [ChordPro](https://www.chordpro.org/), with the
+song's details (title, artists, key, tempo, time, capo, copyright) alongside; sheet music will
+become MusicXML.
+
+A PDF's own text is read first: charts typed up in a word processor or chart app keep their words
+and where each sits on the page, so their chords can be put back over the syllables they are
+played on, without asking anyone. Anything else (scans, photos, sheet music, or text that isn't
+plainly a chord chart) is read by Claude, looking at its pages.
+
+## Installation
+
+```bash
+uv add "songscan @ git+https://github.com/jnhmcknight/songscan.git"
+```
+
+Reading scans needs an [Anthropic API key](https://platform.claude.com/), in `ANTHROPIC_API_KEY`
+or a client you pass in. PDFs with their own text don't use it.
+
+## Usage
+
+```python
+from songscan import ScanError, scan_pdf
+
+try:
+    result = scan_pdf(pdf_bytes)
+except ScanError as error:
+    ...  # error.retryable: whether trying again later may work
+
+result.kind       # "chord_chart", "score" or "other"
+result.chordpro   # a chord chart's ChordPro, details and all; else None
+result.meta       # ScanMeta: title, artists, key, tempo, time, capo, copyright
+result.source     # "text" (the PDF's own) or "vision" (Claude's reading)
+result.warnings   # anything to check, or that couldn't be done
+```
+
+To choose the client or model:
+
+```python
+import anthropic
+
+result = scan_pdf(pdf_bytes, client=anthropic.Anthropic(api_key=...), model="claude-opus-5-5")
+```
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check && uv run black --check . && uv run pyright
+```
+
+Tests that read PDFs with vision use a stand-in for Claude. To run them against the real API
+instead (which costs a little), set `SONGSCAN_LIVE_API=1` with a key in `ANTHROPIC_API_KEY`:
+
+```bash
+SONGSCAN_LIVE_API=1 uv run pytest
+```
+
+Tests of how songscan handles the API's answers and errors use the stand-in either way.

songscan-0.1.0/pyproject.toml

@@ -0,0 +1,87 @@
+[project]
+name = "songscan"
+version = "0.1.0"
+description = "Read songs out of PDFs: chord charts as ChordPro, sheet music as MusicXML"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.13"
+dependencies = [
+    "anthropic",
+    "chordpro-renderer",
+    "pdfplumber",
+    "pydantic>=2",
+]
+
+[[project.authors]]
+name = "Jared McKnight"
+email = "jmcknight@archertech.ca"
+
+[project.urls]
+Homepage = "https://github.com/jnhmcknight/songscan"
+Repository = "https://github.com/jnhmcknight/songscan"
+Issues = "https://github.com/jnhmcknight/songscan/issues"
+
+[tool.uv.sources.chordpro-renderer]
+git = "https://github.com/jnhmcknight/chordpro.git"
+rev = "main"
+
+[tool.uv.build-backend]
+module-root = ""
+module-name = "songscan"
+
+[tool.pytest.ini_options]
+timeout = 15
+testpaths = ["tests"]
+pythonpath = ["."]
+addopts = "--cov=songscan --cov-report=term-missing"
+
+[tool.black]
+line-length = 110
+
+[tool.ruff]
+line-length = 110
+
+[tool.ruff.lint]
+select = [
+    "B",
+    "C4",
+    "FLY",
+    "PERF",
+    "PIE",
+    "PLC0415",
+    "RUF",
+    "SIM",
+    "T20",
+    "TC004",
+    "UP",
+    "F401",
+]
+ignore = [
+    "C408",
+    "PERF401",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["PLC0415"]
+
+[tool.pyright]
+include = ["songscan"]
+useLibraryCodeForTypes = true
+venvPath = "."
+venv = ".venv"
+
+[dependency-groups]
+dev = [
+    "black>=25.1.0",
+    "pyright",
+    "pytest>=8.0",
+    "pytest-cov>=5.0.0",
+    "pytest-randomly>=4.0.1",
+    "pytest-timeout>=2.4.0",
+    "reportlab>=4.0",
+    "ruff",
+]
+
+[build-system]
+requires = ["uv_build>=0.6"]
+build-backend = "uv_build"

songscan-0.1.0/pyproject.toml.orig

@@ -0,0 +1,70 @@
+[project]
+name = "songscan"
+version = "0.1.0"
+description = "Read songs out of PDFs: chord charts as ChordPro, sheet music as MusicXML"
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "Jared McKnight", email = "jmcknight@archertech.ca" },
+]
+requires-python = ">=3.13"
+dependencies = [
+    "anthropic",
+    "chordpro-renderer",
+    "pdfplumber",
+    "pydantic>=2",
+]
+
+[project.urls]
+Homepage = "https://github.com/jnhmcknight/songscan"
+Repository = "https://github.com/jnhmcknight/songscan"
+Issues = "https://github.com/jnhmcknight/songscan/issues"
+
+[tool.uv.sources]
+chordpro-renderer = { git = "https://github.com/jnhmcknight/chordpro.git", rev = "main" }
+
+[dependency-groups]
+dev = [
+    "black>=25.1.0",
+    "pyright",
+    "pytest>=8.0",
+    "pytest-cov>=5.0.0",
+    "pytest-randomly>=4.0.1",
+    "pytest-timeout>=2.4.0",
+    "reportlab>=4.0",
+    "ruff",
+]
+
+[tool.pytest.ini_options]
+timeout = 15
+testpaths = ["tests"]
+pythonpath = ["."]
+addopts = "--cov=songscan --cov-report=term-missing"
+
+[build-system]
+requires = ["uv_build>=0.6"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-root = ""
+module-name = "songscan"
+
+[tool.black]
+line-length = 110
+
+[tool.ruff]
+line-length = 110
+
+[tool.ruff.lint]
+# As the Fanaux backend's: see its pyproject.toml
+select = ["B", "C4", "FLY", "PERF", "PIE", "PLC0415", "RUF", "SIM", "T20", "TC004", "UP", "F401"]
+ignore = ["C408", "PERF401"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["PLC0415"]
+
+[tool.pyright]
+include = ["songscan"]
+useLibraryCodeForTypes = true
+venvPath = "."
+venv = ".venv"

songscan-0.1.0/songscan/__init__.py

@@ -0,0 +1,21 @@
+"""
+songscan
+~~~~~~~~
+
+Read songs out of PDFs: chord charts become ChordPro, and sheet music
+MusicXML.
+
+Usage::
+
+    from songscan import scan_pdf
+
+    result = scan_pdf(pdf_bytes)
+    if result.kind == "chord_chart":
+        save(result.chordpro, key=result.meta.key)
+"""
+
+from .models import ScanError, ScanMeta, ScanResult
+from .scan import scan_pdf
+from .vision import DEFAULT_MODEL
+
+__all__ = ["DEFAULT_MODEL", "ScanError", "ScanMeta", "ScanResult", "scan_pdf"]

songscan-0.1.0/songscan/models.py

@@ -0,0 +1,57 @@
+"""What a scan finds in a PDF."""
+
+from dataclasses import dataclass, field
+from typing import Literal
+
+Kind = Literal["chord_chart", "score", "other"]
+
+
+@dataclass
+class ScanMeta:
+    """The song's details, as far as the PDF shows them."""
+
+    title: str | None = None
+    artists: list[str] = field(default_factory=list)
+    key: str | None = None
+    tempo: str | None = None
+    time: str | None = None
+    capo: str | None = None
+    copyright: list[str] = field(default_factory=list)
+
+    def directives(self) -> list[str]:
+        """These details as ChordPro directives, for the top of a chart."""
+        lines = [f"{{title: {self.title}}}"] if self.title else []
+        lines += [f"{{artist: {artist}}}" for artist in self.artists]
+        for name in ("key", "tempo", "time", "capo"):
+            if value := getattr(self, name):
+                lines.append(f"{{{name}: {value}}}")
+        lines += [f"{{copyright: {line}}}" for line in self.copyright]
+        return lines
+
+
+@dataclass
+class ScanResult:
+    """A PDF, read.
+
+    A chord chart comes with its ChordPro (details and all), and sheet music
+    with its MusicXML; anything else, with neither. `source` says how it was
+    read: from the PDF's own text, or by looking at its pages.
+    """
+
+    kind: Kind
+    meta: ScanMeta
+    pages: int
+    source: Literal["text", "vision"]
+    chordpro: str | None = None
+    musicxml: str | None = None
+    # Things the reader should check, or that couldn't be done
+    warnings: list[str] = field(default_factory=list)
+
+
+class ScanError(Exception):
+    """The PDF couldn't be read. `retryable` when trying again later may work
+    (the vision service was busy or unreachable)."""
+
+    def __init__(self, message: str, *, retryable: bool = False):
+        super().__init__(message)
+        self.retryable = retryable

songscan-0.1.0/songscan/scan.py

@@ -0,0 +1,22 @@
+"""Scanning a PDF: its own text first, which is free and exact, and Claude's
+reading of its pages when that isn't plainly a chord chart."""
+
+import anthropic
+
+from .models import ScanResult
+from .text import chart_from_text, read_text
+from .vision import DEFAULT_MODEL, read_with_vision
+
+
+def scan_pdf(
+    data: bytes, *, client: anthropic.Anthropic | None = None, model: str = DEFAULT_MODEL
+) -> ScanResult:
+    """What the PDF *data* holds: a chord chart (as ChordPro), sheet music, or
+    something else. *client* reads scans and sheet music; by default, one
+    with the environment's API key. Raises ScanError when it can't be read.
+    """
+    text = read_text(data)
+    if text.has_text and not text.music_font and (chart := chart_from_text(text.lines)):
+        chordpro, meta = chart
+        return ScanResult(kind="chord_chart", meta=meta, pages=text.pages, source="text", chordpro=chordpro)
+    return read_with_vision(data, text.pages, client or anthropic.Anthropic(), model)

songscan-0.1.0/songscan/text.py

@@ -0,0 +1,268 @@
+"""Reading a PDF's own text: for charts typed up in a word processor or chart
+app, which keep their words (and where on the page each one is). Their lines
+are rebuilt from where the words sit, so that chords stay above the syllables
+they are played on, and a chord chart is turned into ChordPro without asking
+anyone.
+"""
+
+import io
+import itertools
+import re
+from dataclasses import dataclass, field
+from statistics import median
+
+import pdfplumber
+from pdfminer.pdfparser import PDFSyntaxError
+from pdfplumber.page import Page
+from pdfplumber.utils.exceptions import PdfminerException
+
+from chordpro.chordsheet import chord_line, chord_sheet_to_chordpro, section_kind
+
+from .models import ScanError, ScanMeta
+
+# Below this many characters, a PDF's text is too little to be the song: it
+# is a scan or a picture, perhaps with a page number or a footer
+MIN_TEXT = 40
+
+# Fonts that notation software draws notes with: a PDF using one is sheet music
+MUSIC_FONTS = re.compile(
+    r"bravura|leland|petaluma|emmentaler|feta|gonville|maestro|petrucci|engraver|"
+    r"sebastian|opus|mscore|musisync|november|finale|lilyjazz|musejazz",
+    re.IGNORECASE,
+)
+
+# A chart needs at least this many lines of chords, making up at least this
+# share of its lines
+MIN_CHORD_LINES = 2
+MIN_CHORD_SHARE = 0.15
+
+_KEY_RE = re.compile(r"\bkey\s*(?:of|[:=-])?\s*([A-G][#b♯♭]?m?)\b", re.IGNORECASE)
+_TEMPO_RE = re.compile(r"\b(?:tempo\s*[:=-]?\s*(\d{2,3})|(\d{2,3})\s*bpm)\b", re.IGNORECASE)
+_TIME_RE = re.compile(r"\b(?:time(?:\s*signature)?\s*[:=-]?\s*)?(\d{1,2}/\d{1,2})\b", re.IGNORECASE)
+_CAPO_RE = re.compile(r"\bcapo\s*[:=-]?\s*(\d{1,2})\b", re.IGNORECASE)
+_COPYRIGHT_RE = re.compile(r"©|\(c\)|\bcopyright\b|\bccli\b|\ball rights reserved\b", re.IGNORECASE)
+# Between a header's columns
+_COLUMN_GAP = re.compile(r"\s{4,}")
+_BY_RE = re.compile(r"^\s*(?:words\s+and\s+music\s+)?by\s+", re.IGNORECASE)
+# A section label, once tidied: "Verse 1", "Pre-Chorus 2", "Bridge"
+_SECTION_RE = re.compile(r"[A-Za-z][A-Za-z-]*(?: [A-Za-z][A-Za-z-]*)*(?: ?\d+)?")
+# What may follow a label: "Chorus (x2)", "Chorus x2"
+_REPEAT_RE = re.compile(r"\(? ?x ?\d+ ?\)?$", re.IGNORECASE)
+# Most a label can be: "Pre-Chorus 2", not a lyric that starts with "Bridge"
+_SECTION_WORDS = 3
+
+
+@dataclass
+class PdfText:
+    """A PDF's text, as lines laid out the way they are on its pages."""
+
+    pages: int
+    lines: list[str] = field(default_factory=list)
+    # Characters of text it has, and whether it draws notes in a music font
+    characters: int = 0
+    music_font: bool = False
+
+    @property
+    def has_text(self) -> bool:
+        return self.characters >= MIN_TEXT
+
+
+def read_text(data: bytes) -> PdfText:
+    """The text of the PDF *data*."""
+    try:
+        with pdfplumber.open(io.BytesIO(data)) as pdf:
+            text = PdfText(pages=len(pdf.pages))
+            for page in pdf.pages:
+                if text.lines:
+                    text.lines.append("")
+                text.lines.extend(page_lines(page))
+                text.characters += sum(1 for char in page.chars if not char["text"].isspace())
+                text.music_font = text.music_font or any(
+                    MUSIC_FONTS.search(c["fontname"]) for c in page.chars
+                )
+    except (PdfminerException, PDFSyntaxError, ValueError) as error:
+        raise ScanError(f"This isn't a PDF that can be read: {error}") from error
+    return text
+
+
+def page_lines(page: Page) -> list[str]:
+    """The page's lines of text, each word at the column it starts at, and a
+    blank line where there is a gap between lines (as between sections)."""
+    words = page.extract_words(use_text_flow=False)
+    if not words:
+        return []
+    char_width = median((w["x1"] - w["x0"]) / len(w["text"]) for w in words)
+    height = median(w["bottom"] - w["top"] for w in words)
+    left = min(w["x0"] for w in words)
+
+    # Words on the same line (their tops within half a line of each other)
+    rows: list[list[dict]] = []
+    for word in sorted(words, key=lambda w: (w["top"], w["x0"])):
+        if rows and word["top"] - rows[-1][0]["top"] <= height / 2:
+            rows[-1].append(word)
+        else:
+            rows.append([word])
+
+    rows = [sorted(row, key=lambda w: w["x0"]) for row in rows]
+    tops = [row[0]["top"] for row in rows]
+    gaps = [b - a for a, b in itertools.pairwise(tops)]
+    # Lines further apart than this have a blank line between them
+    blank_gap = median(gaps) * 1.6 if gaps else 0
+
+    placed = [_columns(row, left, char_width) for row in rows]
+    texts = [_line(columns) for columns in placed]
+    # Chords go over the syllables they sit above, wherever the lyric's
+    # (proportional) letters put those in the line
+    for index in range(len(rows) - 1):
+        if (
+            gaps[index] <= blank_gap
+            and chord_line(texts[index]) is not None
+            and chord_line(texts[index + 1]) is None
+        ):
+            placed[index] = _over(rows[index], placed[index + 1], left, char_width)
+            texts[index] = _line(placed[index])
+
+    lines = []
+    for index, text in enumerate(texts):
+        if index and gaps[index - 1] > blank_gap:
+            lines.append("")
+        lines.append(text)
+    return lines
+
+
+def _columns(row: list[dict], left: float, char_width: float) -> list[tuple[int, dict]]:
+    """Each of a line's words, with the column it starts at."""
+    columns: list[tuple[int, dict]] = []
+    end = -1  # where the word before ends, and a space after it
+    before = None
+    for word in row:
+        own_width = (word["x1"] - word["x0"]) / len(word["text"])
+        if before is not None and word["x0"] - before["x1"] < own_width * 1.5:
+            column = end + 1  # an ordinary space, however large the font
+        else:
+            column = max(round((word["x0"] - left) / char_width), end + 1)
+        columns.append((column, word))
+        end = column + len(word["text"])
+        before = word
+    return columns
+
+
+def _over(chords: list[dict], lyric: list[tuple[int, dict]], left: float, char_width: float):
+    """The columns of a line of *chords* over a *lyric*: each over the letter
+    of the lyric's word that it starts above."""
+    columns: list[tuple[int, dict]] = []
+    end = -1
+    for chord in chords:
+        column = round((chord["x0"] - left) / char_width)
+        for start, word in lyric:
+            width = (word["x1"] - word["x0"]) / len(word["text"])
+            if word["x0"] - width / 2 <= chord["x0"] < word["x1"]:
+                column = start + min(round((chord["x0"] - word["x0"]) / width), len(word["text"]) - 1)
+                break
+            if chord["x0"] >= word["x1"]:
+                # Past this word: as far past its end as the chord is
+                column = start + len(word["text"]) + max(round((chord["x0"] - word["x1"]) / char_width), 1)
+        column = max(column, end + 1)
+        columns.append((column, chord))
+        end = column + len(chord["text"])
+    return columns
+
+
+def _line(columns: list[tuple[int, dict]]) -> str:
+    line = ""
+    for column, word in columns:
+        line = line.ljust(column) + word["text"]
+    return line
+
+
+def section(line: str) -> tuple[str, str] | None:
+    """The ChordPro section and label a chart's line opens, if it is a label."""
+    label = " ".join(line.split())  # one space between words
+    label = _REPEAT_RE.sub("", label).strip()
+    label = label.removeprefix("[").removesuffix(":").removesuffix("]").strip()
+    if len(label.split()) > _SECTION_WORDS or not _SECTION_RE.fullmatch(label):
+        return None
+    kind = section_kind(label)
+    if kind is None:
+        return None
+    # Labels in capitals read as shouting in ChordPro's: "VERSE 1" → "Verse 1"
+    return kind, label.title() if label.isupper() else label
+
+
+def is_chord_chart(lines: list[str]) -> bool:
+    """Whether *lines* are a chord chart: lines of chords, over lyrics or not."""
+    text = [line for line in lines if line.strip()]
+    chords = sum(1 for line in text if chord_line(line) is not None)
+    return chords >= MIN_CHORD_LINES and chords / len(text) >= MIN_CHORD_SHARE
+
+
+def chart_from_text(lines: list[str]) -> tuple[str, ScanMeta] | None:
+    """The ChordPro, and the details, of a chord chart's lines; None when they
+    aren't a chord chart."""
+    if not is_chord_chart(lines):
+        return None
+    meta = ScanMeta()
+
+    # Copyright lines may be anywhere, often at the foot of the page
+    body = []
+    for line in lines:
+        if _COPYRIGHT_RE.search(line):
+            meta.copyright.append(line.strip())
+        else:
+            body.append(line)
+
+    # The details are at the top, before the first chords or section label
+    start = next(
+        (i for i, line in enumerate(body) if chord_line(line) is not None or section(line)),
+        len(body),
+    )
+    # Often in two columns, the title on the left and the details on the right
+    aside = []
+    for line in body[:start]:
+        left, *right = _COLUMN_GAP.split(line.strip())
+        aside.extend(right)
+        if not left or _details(left, meta):
+            continue
+        if meta.title is None:
+            meta.title = left
+        elif not meta.artists:
+            meta.artists = [_BY_RE.sub("", left)]
+    _details(" ".join(aside), meta, whole_line=False)
+    # The details may also share a line with the first chords' label
+    for line in body[start : start + 3]:
+        _details(line, meta, whole_line=False)
+
+    content = _unindent(chord_sheet_to_chordpro(body[start:], section))
+    return "\n".join([*meta.directives(), "", *content]), meta
+
+
+def _unindent(chordpro: list[str]) -> list[str]:
+    """*chordpro* without the margins of the page it came from. Its chords
+    are in its lyrics, so this can't move them; tabs keep their spacing."""
+    lines, tab = [], False
+    for line in chordpro:
+        if line.startswith("{start_of_tab"):
+            tab = True
+        elif line.startswith("{end_of_tab"):
+            tab = False
+        lines.append(line if tab else line.strip())
+    return lines
+
+
+def _details(line: str, meta: ScanMeta, whole_line: bool = True) -> bool:
+    """Fill in *meta* with the key, tempo, time or capo *line* gives; whether
+    it gave any (and, with *whole_line*, was nothing but those)."""
+    found = False
+    for pattern, name in ((_KEY_RE, "key"), (_TEMPO_RE, "tempo"), (_CAPO_RE, "capo")):
+        if (m := pattern.search(line)) and getattr(meta, name) is None:
+            setattr(meta, name, next(g for g in m.groups() if g))
+            found = True
+    if (m := _TIME_RE.search(line)) and meta.time is None and (found or "time" in line.lower() or whole_line):
+        meta.time = m.group(1)
+        found = True
+    if not whole_line:
+        return found
+    rest = line
+    for pattern in (_KEY_RE, _TEMPO_RE, _TIME_RE, _CAPO_RE):
+        rest = pattern.sub("", rest)
+    return found and not re.sub(r"[\s|,;·•/-]+", "", rest)

songscan-0.1.0/songscan/vision.py

@@ -0,0 +1,118 @@
+"""Reading a PDF by looking at its pages, with Claude: for scans and photos of
+charts, which have no text of their own, and to tell what a PDF is when its
+text isn't plainly a chord chart.
+"""
+
+import base64
+from typing import Literal
+
+import anthropic
+from anthropic.types.beta import BetaMessageParam, BetaRequestDocumentBlockParam
+from pydantic import BaseModel, Field
+
+from .models import ScanError, ScanMeta, ScanResult
+
+DEFAULT_MODEL = "claude-opus-5-5"
+
+# Falls back to another model, picked by why, should the model decline
+_FALLBACK_BETA = "server-side-fallback-2026-07-01"
+
+SYSTEM = """\
+You read PDFs of songs for a church worship team's song library, and turn each into data the library \
+can store. Musicians will play from what you write, so accuracy matters more than completeness.
+
+First, decide what the PDF is:
+- chord_chart: lyrics with chord names (above the words, or inline), or a chart of chords alone.
+- score: sheet music, with notes on staves: lead sheets, piano/vocal, choral or instrumental parts.
+- other: anything else, such as lyrics without chords.
+
+For a chord_chart, write the song in ChordPro as `chordpro`:
+- Put each chord in square brackets just before the syllable it is played on: "[G]Amazing [C]grace". \
+Use the chord names exactly as written.
+- Wrap each section in a start and end directive with the chart's own label, such as \
+"{start_of_verse: Verse 1}" ... "{end_of_verse}". The kinds are verse, chorus, prechorus, bridge, \
+intro, outro, tag, interlude and instrumental.
+- A line of chords with no lyrics stays a line of bracketed chords: "[G] [C] [D]".
+- Instructions to the band, such as "Repeat x2" or "Build", become "{comment: Repeat x2}".
+- Copy what the PDF shows, as it shows it: don't correct, complete, transpose or reorder anything, \
+and write out a section again only where the PDF does.
+- Leave the title, artists, key, tempo, time signature, capo and copyright out of `chordpro`: \
+they have fields of their own.
+For a score or other, `chordpro` is null.
+
+Fill in the song's details only from what the PDF shows, and null (or an empty list) for anything \
+it doesn't: the title, the artists or writers, the key (like "G", "B♭" or "F♯m"), the tempo in beats \
+per minute (digits only), the time signature (like "4/4"), the capo fret (digits only), and the \
+copyright lines, one per line, including any CCLI song number.
+"""
+
+
+class _Song(BaseModel):
+    """What the model makes of a PDF."""
+
+    kind: Literal["chord_chart", "score", "other"]
+    title: str | None
+    artists: list[str]
+    key: str | None
+    tempo: str | None
+    time: str | None
+    capo: str | None
+    copyright: list[str]
+    chordpro: str | None = Field(description="The chord chart in ChordPro, without its details.")
+
+
+def read_with_vision(data: bytes, pages: int, client: anthropic.Anthropic, model: str) -> ScanResult:
+    """What Claude makes of the PDF *data* (of *pages* pages)."""
+    document: BetaRequestDocumentBlockParam = {
+        "type": "document",
+        "source": {
+            "type": "base64",
+            "media_type": "application/pdf",
+            "data": base64.b64encode(data).decode(),
+        },
+    }
+    message: BetaMessageParam = {
+        "role": "user",
+        "content": [document, {"type": "text", "text": "Read this PDF."}],
+    }
+    try:
+        response = client.beta.messages.parse(
+            model=model,
+            max_tokens=16000,
+            system=SYSTEM,
+            messages=[message],
+            output_format=_Song,
+            output_config={"effort": "medium"},
+            fallbacks="default",
+            betas=[_FALLBACK_BETA],
+        )
+    except (anthropic.RateLimitError, anthropic.InternalServerError, anthropic.APIConnectionError) as error:
+        raise ScanError(f"The PDF couldn't be read just now: {error}", retryable=True) from error
+    except anthropic.APIStatusError as error:
+        raise ScanError(f"The PDF couldn't be read: {error.message}") from error
+
+    if response.stop_reason == "refusal":
+        raise ScanError("The PDF couldn't be read: reading it was declined.")
+    if response.stop_reason == "max_tokens":
+        raise ScanError("The PDF couldn't be read: it is too long.")
+    song = response.parsed_output
+    if song is None:
+        raise ScanError("The PDF couldn't be read: no song came back.")
+
+    meta = ScanMeta(
+        title=song.title,
+        artists=song.artists,
+        key=song.key,
+        tempo=song.tempo,
+        time=song.time,
+        capo=song.capo,
+        copyright=song.copyright,
+    )
+    result = ScanResult(kind=song.kind, meta=meta, pages=pages, source="vision")
+    if song.kind == "chord_chart" and song.chordpro:
+        result.chordpro = "\n".join([*meta.directives(), "", song.chordpro.strip()])
+    elif song.kind == "chord_chart":
+        result.warnings.append("No chords or lyrics could be read from this chart.")
+    elif song.kind == "score":
+        result.warnings.append("Sheet music isn't read into MusicXML yet.")
+    return result