instrumentaipdfsplitter 5.0.0

AI-assisted instrument part detector and PDF splitter

Instrument AI PDF Splitter

A lightweight Python tool that uses OpenAI to analyze multi-page sheet-music PDFs, detect instrument parts (including voice/desk numbers), determine their page ranges, and split the source PDF into one file per instrument/voice.

• AI-assisted part detection: extracts instruments, voice numbers, and 1-indexed start/end pages as strict JSON.
• Smart uploads: avoids re-uploading identical files via SHA-256 hashing.
• Reliable splitting: clamps page ranges, sanitizes filenames, and writes outputs using pypdf.
• Flexible input: use AI analysis or provide your own instrument list (InstrumentPart or JSON).
• Configurable model: via constructor or OPENAI_MODEL env var; requires an OpenAI API key.

Installation

pip install instrumentaipdfsplitter

Requirements:

• Python 3.10+
• openai (>= 1.0.0)
• pypdf
• dataclasses (builtin)
• typing, pathlib, etc. (builtin)

Quickstart

import os
import json
from InstrumentAiPdfSplitter import InstrumentAiPdfSplitter

# Set your OpenAI API key via env or pass directly
api_key = os.getenv("OPENAI_API_KEY")

splitter = InstrumentAiPdfSplitter(api_key=api_key)

# 1) Analyze the PDF to get instrument parts and page ranges
data = splitter.analyse("scores/book.pdf")
print(json.dumps(data, indent=2))

# Example output (JSON):
# {
#   "instruments": [
#     {"name": "Trumpet in Bb", "voice": "1", "start_page": 3, "end_page": 5},
#     {"name": "Alto Sax", "voice": null, "start_page": 6, "end_page": 9}
#   ]
# }

# 2) Split the PDF into one file per instrument/voice
results = splitter.split_pdf("scores/book.pdf")
for r in results:
    print(f"{r['name']} {r['voice']} -> {r['output_path']} [{r['start_page']}-{r['end_page']}]")

One-liner

If you just want to analyse and split in one go:

results = splitter.analyse_and_split("scores/book.pdf")

Single-part analysis (extract instrument and voice)

If your PDF contains a single instrument part and you only want to extract its information:

info = splitter.analyse_single_part("scores/trumpet1.pdf")
print(info)
# Example: {"name": "Trumpet in Bb", "voice": "1", "start_page": 1, "end_page": 3, "pages": 3}

By default, output files are saved into a sibling directory named "_parts" (e.g., book_parts). To change the output location, pass out_dir. To avoid writing to disk entirely and get the split PDFs back as in-memory bytes, set return_files=True:

# Return split PDFs without writing them to disk
results = splitter.split_pdf("scores/book.pdf", return_files=True)
for r in results:
    print(r["filename"], len(r["content"]))  # content is bytes for the PDF

# One-liner variant
results = splitter.analyse_and_split("scores/book.pdf", return_files=True)

Manual instrument data (no AI call)

You can skip analysis and provide parts manually, either as InstrumentPart instances or JSON-like dicts.

from InstrumentAiPdfSplitter import InstrumentAiPdfSplitter, InstrumentPart

splitter = InstrumentAiPdfSplitter(api_key="YOUR_OPENAI_API_KEY")

parts = [
    InstrumentPart(name="Trumpet in Bb", voice="1", start_page=3, end_page=5),
    {"name": "Alto Sax", "voice": None, "start_page": 6, "end_page": 9},  # JSON-like dict also works
]

results = splitter.split_pdf(
    pdf_path="scores/book.pdf",
    instruments_data=parts,
    out_dir="output/parts"  # optional custom directory
)

for r in results:
    print(r)

Configuration

• API key: Provide via constructor or set OPENAI_API_KEY in your environment.
• Model: Pass model to the constructor or set OPENAI_MODEL; defaults to "gpt-5".

splitter = InstrumentAiPdfSplitter(api_key="...", model="gpt-5")

Note: Model availability depends on your OpenAI account. Use a model that supports the Responses API with file inputs. You will get the best results with gpt-5.

How it works

• Content-hash uploads: Files are uploaded once per SHA-256; duplicates are skipped.
• AI analysis: The PDF and a strict prompt are sent to OpenAI; output is parsed as JSON.
• Splitting:
  • Ensures pages are 1-indexed and within document bounds.
  • Swaps start/end if reversed.
  • Sanitizes output filenames (removes unsafe characters).
  • Writes per-part PDFs using pypdf.

Public API

Item	Signature	Description
InstrumentPart	name: str; voice: Optional[str]; start_page: int; end_page: int	Dataclass representing a single instrument part with optional voice and 1-indexed inclusive page range.
InstrumentAiPdfSplitter.init	(api_key: str, *, model: str	None = None) -> None
InstrumentAiPdfSplitter.analyse	(pdf_path: str) -> dict	Analyze a PDF and return instrument data as JSON {instruments: [...]}.
InstrumentAiPdfSplitter.analyse_and_split	(pdf_path: str, out_dir: Optional[str] = None, *, return_files: bool = False) -> List[Dict[str, Any]]	Convenience: analyse then split in one call; set return_files=True to get in-memory PDFs.
InstrumentAiPdfSplitter.analyse_single_part	(pdf_path: str) -> Dict[str, Any]	Analyse a single-part PDF and extract instrument name and optional voice; returns also start/end/pages.
InstrumentAiPdfSplitter.is_file_already_uploaded	(pdf_path: str) -> Tuple[bool, str]	Check if a file (by SHA-256) is already uploaded; returns (True, file_id) or (False,).
InstrumentAiPdfSplitter.split_pdf	(pdf_path: str, instruments_data: List[InstrumentPart]	Dict[str, Any]
InstrumentAiPdfSplitter.file_hash	(path: str) -> str	Compute SHA-256 hex digest of a file’s contents.

Error handling

• FileNotFoundError: Path doesn’t exist.
• ValueError: Not a file or not a .pdf.
• json.JSONDecodeError: If AI output isn’t valid JSON (rare; retry or adjust model).
• OpenAI errors: Network/auth/model issues are propagated from the OpenAI SDK.

Tips for best results

• Use clear, well-structured PDFs with visible instrument headers or page titles.
• If AI is uncertain, manually provide instruments_data for precise splitting.
• Verify the model supports file inputs in your region/account.
• Handle sensitive material carefully; PDFs are uploaded to OpenAI for analysis.

Example project structure

scores/
├── book.pdf
output/
└── parts/
    ├── 01 - Trumpet in Bb 1.pdf
    ├── 02 - Alto Sax.pdf
    └── ...

Development

# Clone and install locally
git clone REPO_URL
cd REPO_DIR
pip install -e .

# Run a quick test (adjust paths)
python -c "from InstrumentAiPdfSplitter import InstrumentAiPdfSplitter; import os; s=InstrumentAiPdfSplitter(api_key=os.getenv('OPENAI_API_KEY')); print(s.file_hash('scores/book.pdf'))"

Versioning and compatibility

• Tested with Python 3.10+.
• Requires openai>=1.0.0 and pypdf. Keep dependencies updated.

FAQ

• Does it require internet?
  • Yes, for AI analysis. Splitting runs locally.
• Can I prevent re-uploads?
  • Yes. The tool checks a SHA-256 content hash against your uploaded files.
• Is the output deterministic?
  • The JSON structure is deterministic; the content depends on model interpretation.

License

Copyright (c) 2025 Flinn

Permission is hereby granted to use, copy, and distribute this software in unmodified form, provided that proper attribution is given to the author. Modification, merging, or creation of derivative works based on this software is strictly prohibited.

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 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.

Acknowledgments

• Built with pypdf and the OpenAI Python SDK.