DEV Community: Baurzhan Zhetenov

5 Weird Bugs I Hit Capturing System Audio Cross-Platform (Rust + Tauri)

Baurzhan Zhetenov — Sat, 05 Sep 2026 10:52:01 +0000

Full disclosure up front: I'm building SyntaxCue, a desktop app that listens to a live call and helps you think through the answer in real time. None of that matters for this post — this is the engineering diary from getting system-audio capture working the same way on macOS and Windows.

"System audio" sounds like it should be one API. It isn't. macOS gives you the CoreAudio Process Tap (Swift-only, no Rust bindings), and Windows gives you WASAPI opened in a mode nobody advertises as "the loopback mode." I already wrote up the full architecture — this post is the part that doesn't fit an architecture writeup: the five bugs that only show up once you actually run the thing.

Bug 1: a binary PCM stream deadlocked a line-buffered reader

The Process Tap API is Swift-only, so the macOS side runs as a small Swift sidecar binary that streams raw audio to Rust over stdout — plain interleaved 32-bit float samples, nothing else. Tauri's shell plugin reads a child process's stdout as text lines by default, splitting on \n (0x0A).

That's fine for JSON-over-stdout. It is not fine for raw float samples, because 0x0A shows up by chance inside arbitrary audio data — and, worse, during silence (all-zero bytes), it never shows up at all. A line-buffered reader waiting for a "line" that silence will never produce just waits. Forever. The pipe backs up, the child's writes block, and the helper hangs before it ever streams a single real sample.

Fix was one flag:

let (mut rx, child) = app
    .shell()
    .sidecar("syntaxcue-audiotap")?
    .set_raw_out(true)   // <- this
    .spawn()?;

set_raw_out(true) treats stdout as raw bytes instead of scanning for line breaks. Obvious once you've hit it; invisible until you have, because the failure looks exactly like "the whole thing is just hanging," not "reading stdout wrong."

Bug 2: a killed process left a tap that looked fine and captured nothing

macOS's Process Tap has to be wrapped in a private aggregate device before you can pull audio through a normal IO cycle — AudioHardwareCreateProcessTap, then AudioHardwareCreateAggregateDevice wrapping it. Both are real CoreAudio objects with real lifecycles.

Force-kill the sidecar mid-test (which happens constantly in development) without giving it a chance to clean up, and CoreAudio doesn't always reclaim the tap and aggregate device promptly. The next run creates a new tap successfully — no error, no permission prompt, nothing — and then delivers exactly zero bytes of audio. From the outside this is indistinguishable from a real capture bug, and I spent longer than I'd like to admit debugging "capture" logic that was working fine against an orphaned device.

The fix is explicit teardown on every exit path, including signals — and it has to go through DispatchSource, not a raw signal() handler, because tearing down CoreAudio objects allocates and talks to XPC, which isn't safe from an actual signal handler:

signal(SIGTERM, SIG_IGN)
let sigtermSource = DispatchSource.makeSignalSource(signal: SIGTERM, queue: .main)
sigtermSource.setEventHandler {
    AudioDeviceStop(aggregateID, procID)
    AudioDeviceDestroyIOProcID(aggregateID, procID)
    AudioHardwareDestroyAggregateDevice(aggregateID)
    AudioHardwareDestroyProcessTap(tapID)
    exit(0)
}
sigtermSource.resume()

Now killing the process actually tears the tap down instead of just ending the process that was holding it.

Bug 3: WASAPI's idle endpoint doesn't send silence — it sends nothing

Windows loopback capture works by opening the default playback device in the Capture direction — there's no separate "what's playing" device to enumerate. Fine so far. The part that isn't documented anywhere obvious: a render endpoint that isn't currently playing anything doesn't hand you silent buffers. It hands you no buffers at all. get_next_packet_size() just returns 0, indefinitely, for as long as the call is quiet.

An event-driven design assumes the event handle fires when there's something to read. On an idle endpoint it never fires — so an event-driven loop would just hang the moment the other person on the call stopped talking, which is, unhelpfully, most of a call.

The fix is polling instead of waiting on the event, and manually synthesizing the elapsed silence so the voice-activity logic downstream still sees time passing:

if frames == 0 {
    let now = Instant::now();
    if let Some(since) = idle_since.replace(now) {
        let elapsed = now.duration_since(since).as_secs_f64();
        let samples = (elapsed * TARGET_RATE as f64) as usize;
        vad.push(app, &vec![0u8; samples * BYTES_PER_FRAME]);
    }
    std::thread::sleep(poll_interval);
    continue;
}

Without this, an utterance that ended right as the line went quiet would just sit in the buffer, waiting to get merged into whatever gets said next — two separate answers transcribed as one run-on sentence.

Bug 4: the "silent" flag isn't telling you the buffer is zeroed

Related, smaller, and sneakier: when WASAPI does deliver a buffer flagged AUDCLNT_BUFFERFLAGS_SILENT, that flag means "treat this as silence" — it does not mean the buffer's memory is actually zeroed. The contents are explicitly undefined at that point.

Skip that check and you're not capturing silence, you're capturing whatever happened to be sitting in that memory — which whisper.cpp will happily attempt to transcribe as if it were real audio.

if info.flags.silent {
    buffer.fill(0);
}

One line, easy to skip, and the failure mode if you do skip it is "occasional garbage phrases with no audio behind them" — which looks exactly like a transcription-model hallucination, not a buffer-handling bug, unless you already know to suspect this flag.

Bug 5: an atexit handler that can't safely take the lock it needs

Last one, and it's about a constraint rather than a bug that shipped: the app needs to guarantee the macOS sidecar gets a SIGTERM when the whole app quits from the menu (not just when the user clicks "stop"), so it doesn't leave an orphaned tap for Bug 2 to bite the next run. That cleanup runs from an atexit handler — which has no AppHandle, runs at a point where you can't assume anything about what other threads are doing, and must not block trying to acquire a mutex another thread might already be holding during shutdown.

So the sidecar's PID lives in two places on purpose: the real Option<CommandChild> behind a Mutex for normal control flow, and a plain AtomicI32 mirror that the atexit guard reads lock-free:

static SIDECAR_PID: AtomicI32 = AtomicI32::new(0);

pub(crate) fn kill_sidecar_on_exit() {
    let pid = SIDECAR_PID.swap(0, Ordering::SeqCst);
    if pid > 0 {
        unsafe { kill(pid, SIGTERM) };
    }
}

Not elegant — it's genuinely two sources of truth for one PID — but it's the boring, correct answer to "what can I safely read from a shutdown handler," which is: as little as possible, and never a lock.

Same problem, two completely different failure shapes

None of these are hard bugs individually. What made them worth writing down is that macOS and Windows failed in opposite directions for what's nominally the same task — capture system audio, hand back the same PCM format. macOS fails by lying: the tap looks fine, permission is granted, and it just quietly hands you nothing. Windows fails by omission: it doesn't hand you anything at all, and the absence itself is the signal you have to design around. Cross-platform audio capture isn't one API with two skins on it — it's two completely different failure surfaces wearing the same output format.

If you want the full pipeline this feeds into — VAD segmentation, local whisper.cpp transcription, streaming the answer back from the user's own LLM key — that's the architecture write-up. And if you're curious what it's actually for: syntaxcue.com.

Why Copying Bank Statement PDFs Into Excel Goes So Wrong

Baurzhan Zhetenov — Sat, 05 Sep 2026 10:32:10 +0000

If you've ever copied transactions from a bank statement PDF into Excel, you've probably seen the mess: broken columns, missing rows, numbers in the wrong places.

It looks like a table on your screen, so why doesn't it behave like one?

I kept running into this problem while building Bank Parser (https://bank-parser.com). I ended up writing a more detailed technical explanation on the site here: Why Bank Statement PDFs Break in Excel (https://bank-parser.com/blog/why-bank-statement-pdfs-break-excel).

The short version is that a PDF and a spreadsheet think about data in completely different ways.

A PDF looks structured. It often isn't.

When you open a bank statement, you might see something like a row: date 05/02, description STARBUCKS STORE #1821, debit -6.45.

Visually, that's obviously a row of transaction data lined up in columns.

But internally, a PDF usually doesn't contain a real table with rows and columns. It stores text and numbers as individual elements positioned at specific X/Y coordinates on a page.

The table is essentially an illusion created by layout.

That works perfectly for displaying and printing the statement. It becomes a problem when another program tries to reconstruct the underlying data.

Excel has to guess where the columns and rows are. And bank statements give it plenty of opportunities to guess wrong.

Four things that commonly break

1. Columns stop lining up

PDFs position text rather than storing consistent spreadsheet-style column widths.

So when Excel interprets spacing as column boundaries, a small difference can move a value into the wrong place.

A date and description might end up together. An amount can shift into the description column. Debit and credit values can stop lining up with their transactions.

The result may still look like data, but it's no longer reliable data.

2. Transactions disappear or split apart

Bank statements frequently use multi-line descriptions.

One transaction might occupy two or three visual lines. When you paste it into Excel, those lines can become separate rows, merge incorrectly, or otherwise confuse the structure.

That creates a particularly nasty problem for bookkeeping: a transaction can appear to have disappeared, or you can accidentally create duplicates.

3. Numbers move into the wrong column

Financial statements often right-align numerical values.

When the PDF layout is interpreted incorrectly, something like 245.50 might end up attached to the description instead of appearing under Debit or Credit.

This is more than a formatting annoyance. If you're importing or reconciling financial data, the transaction direction matters.

4. Formatting gets mistaken for data

Statements can contain merged cells, headers, horizontal separators, subtotal rows, and other visual elements.

Those are useful to a human reader.

During copy-paste, however, they can create blank rows, merged columns, or other artifacts that have nothing to do with the actual transactions.

The important distinction: OCR vs. structured parsing

There's another misconception I ran into while working on this: PDF extraction and OCR aren't necessarily the same thing.

OCR (Optical Character Recognition) is useful when the document is essentially an image. It reads characters from that image and tries to turn them into text. That's exactly what you need for a scanned or photographed statement.

But OCR can introduce its own problems: broken decimals, merged rows, and incorrect column assignments. It recognizes a number, but it doesn't automatically know whether that number represents a debit or a credit.

A native PDF downloaded directly from online banking is different. It already contains a text layer. For those files, you can extract the underlying text directly and use the document's structure and transaction patterns to reconstruct the rows.

That's the approach Bank Parser uses for Chase, Bank of America, Wells Fargo, and Capital One. Its specialized parsers use structured parsing rather than OCR for native PDFs, with OCR used only when the input is a scanned image.

The parser looks at things like transaction positioning, multi-line descriptions, bank-specific patterns, and balance information rather than simply trying to reproduce what the page looks like.

For those native PDFs, accuracy reaches 95-100% with balance verification.

So what actually works?

If you only have one statement with a handful of transactions, manually cleaning up a pasted table may be perfectly reasonable.

But the economics change quickly when you're dealing with bookkeeping.

Twelve monthly statements for one client is already a different problem. Add multiple accounts or multiple clients, and manually repairing broken rows and columns becomes a recurring job.

The better approach is to extract the transactions as structured financial data in the first place.

For the four banks with specialized parsers (Chase, Bank of America, Wells Fargo, and Capital One), Bank Parser can produce a 17-field QuickBooks-ready output.

For other banks, the universal converter extracts a simpler three-column structure.

The goal isn't to make the PDF look like Excel. It's to reconstruct the transactions so Excel actually contains usable financial data.

Try Bank Parser (https://bank-parser.com)

How I capture system audio and transcribe it locally, with no server in the loop (Tauri + Rust + whisper.cpp)

Baurzhan Zhetenov — Wed, 02 Sep 2026 09:28:03 +0000

Disclosure: I'm the developer of the product this pipeline belongs to (SyntaxCue, a live-interview assistant), so treat this as an engineering writeup with an obvious source, not a neutral third-party post. Cross-posted from the original with a canonical link back.

I built a tool that listens to a live technical interview and streams an answer suggestion in a few hundred milliseconds, on-device, without ever recording the call or sending audio anywhere. This is a walkthrough of the actual pipeline — the OS audio API, voice-activity detection, local transcription, and the streamed model response — with the real APIs and the real measured numbers, not the marketing version.

The pipeline, end to end

Four stages: capture system audio → cut the continuous stream into utterances → transcribe each utterance locally → send the text to the user's own LLM and stream the answer back. Capture is the only stage that's platform-specific. Everything after it is shared code that never learns which OS produced the bytes.

1. Capturing system audio, not the microphone

The first design decision drives everything downstream: it listens to system audio — the mixed output of whatever's playing, i.e. the call — not the microphone. That's why it never has to solve "is this the candidate's voice or the interviewer's?" It captures the same mixed output a screen recorder's audio track would, not two separate input channels. There's nothing to diarize; there's one stream.

On macOS (14.2+, Sonoma or later), this uses the CoreAudio Process Tap API: AudioHardwareCreateProcessTap with a CATapDescription configured as monoGlobalTapButExcludeProcesses — a system-wide tap, not scoped to one application — with isPrivate = true and, importantly, muteBehavior = .unmuted. That last flag matters: the tap reads a copy of the stream while the user keeps hearing their call completely normally. Nothing is intercepted, muted, or rerouted.

A raw process tap isn't independently readable. To pull audio through a normal CoreAudio IO cycle, it has to be wrapped in a private aggregate device via AudioHardwareCreateAggregateDevice, which then delivers buffers through a standard IO callback. This part runs as a small Swift sidecar binary, compiled separately and shipped alongside the main Tauri binary, because the Process Tap API has no Rust binding — it's Swift/Objective-C only. So on macOS there are two processes: the Rust/Tauri app and a thin Swift audio helper feeding it PCM.

On Windows, capture uses WASAPI loopback, and it runs entirely in-process — no separate sidecar, unlike macOS. WASAPI is plain COM, reachable directly from the Rust process, so there's no second binary to build, bundle, or code-sign on this platform. Two details shape how this actually works, and they're less obvious than "loopback capture" makes it sound:

Loopback is a render endpoint opened for capture. There's no separate "what's playing" device to enumerate. You take the default playback device and initialize its audio client in the Capture direction — that's specifically what sets AUDCLNT_STREAMFLAGS_LOOPBACK. Nothing here ever asks for a microphone.
It polls instead of being event-driven. WASAPI's event handle only signals while the render endpoint is actively pulling buffers — on a silent or idle endpoint, it never fires, so an event-driven loop would simply hang the moment the call goes quiet. Polling avoids that, and gives the idle branch a place to synthesize the silence the endpoint stops delivering once nothing is playing.

Both platforms converge on exactly the same wire format before anything else touches the audio: raw interleaved PCM, 32-bit float, 16 kHz, mono. From here on, voice-activity detection and transcription are identical shared code that doesn't know or care whether a CoreAudio aggregate device or a WASAPI loopback client produced the samples.

2. Cutting the stream into utterances

A continuous PCM stream isn't transcribable as-is — something has to decide where one spoken chunk ends. This uses energy-based voice-activity detection: plain RMS amplitude thresholding, no ML model for this step.

The rules, exactly:

Silence is any window with RMS amplitude below 0.006.
A segment closes and is sent to transcription once the stream has been voiced (had signal above threshold) and either: (a) silence has run for ≥0.7 seconds and the segment so far is ≥1.0 second long, or (b) the segment hits a hard cap of 20 seconds, so an unbroken monologue doesn't grow unbounded before transcription even starts.
Independently of segmentation, a live audio-level meter is emitted to the UI roughly every 100 ms, so there's continuous visual confirmation that audio is being captured, whether or not a segment has closed yet.

The interesting part is why this is deliberately unsophisticated. A neural VAD would be more precise about exact speech boundaries, but precision isn't the bottleneck here — latency and CPU cost are, on a stage that runs continuously against a live stream. More importantly, a wrong split is cheap: if the RMS heuristic closes a segment slightly early or late, the transcription step just receives a marginally short or long chunk of the same speech, not a wrong one. When the cost of an error is that low, a neural model in the hot path is the wrong trade.

3. Transcription, fully local

Each closed segment goes to whisper.cpp, running on-device. No audio and no transcription text leave the machine at this stage, or any other. The GPU backend is platform-specific: Metal on macOS, Vulkan on Windows. The bundled default model is whisper.cpp's Small model, shipped with the app; larger models are optional downloads. No word-error-rate figure has been benchmarked for it, so none is quoted.

The measured cost that matters is model load — a one-time cost paid once, not per question: ~271 ms on macOS with Metal, versus ~650–870 ms on a Windows machine without GPU acceleration (CPU-only). Per-utterance transcription latency for Metal hasn't been separately isolated the way it was for Windows, so rather than invent a number to make the comparison symmetric, that side just isn't quoted — the load figure is the one that's actually been measured.

The Windows number, though, is a story worth telling in full, because it changed how I think about "cross-platform."

Why I measured instead of assuming

The initial assumption about Windows was the boring, reasonable one: it'd be "a bit slower than the Mac." Same model, same code above the capture layer — expect a tuning-level difference.

The reality wasn't a tuning difference. Before the Vulkan backend was wired up, whisper.cpp on Windows ran CPU-only, and it paid a fixed ~25-second cost per transcription pass — regardless of utterance length. A one-second "yes, exactly" and a fifteen-second answer cost the same 25 seconds. For a tool whose entire value is answering within the few seconds a candidate has to respond, that isn't slow — it's non-functional. Twenty-five seconds per utterance means the answer to the first question arrives around the time the interviewer is asking the third.

The instinct in that situation is to start tuning: a smaller model, shorter segments, thread-count knobs. All of that would have treated a symptom. The actual cause was that there was no GPU backend at all on Windows — whisper.cpp was doing the entire inference on CPU because nothing had told whisper-rs to use the GPU. It wasn't a slow path; it was the wrong path entirely.

Wiring up the Vulkan backend for whisper-rs on Windows changed the numbers by two orders of magnitude. Warm transcription of a ~6-second utterance dropped to ~330 ms. There's a one-time ~8-second GPU "warm-up" on the very first transcription of a session — paid once, not per question — and after that, warm passes are in the range the product actually needs.

The lesson generalizes past this one bug: assuming rough parity between platforms and tuning from there would have meant chasing a 20% improvement on a path that was 100× off for a categorical reason. The gap between 25 seconds and 330 milliseconds wasn't hiding in a config value; it was a missing backend. You only find that by measuring the real number on the real machine instead of reasoning about what should be comparable. Cross-platform parity is a hypothesis, not a default.

4. The answer streams from the user's own model

Once an utterance is transcribed, the text (optionally with a screenshot image) goes out over direct HTTPS to the user's own LLM provider — either api.anthropic.com/v1/messages or api.openai.com/v1/chat/completions, whichever they configured, authenticated with their API key. There is no server of mine anywhere in this path; the request goes from the user's machine straight to Anthropic or OpenAI and nowhere else.

There's no official Anthropic or OpenAI SDK for Rust, so these are direct HTTP calls against the documented wire formats — the response body is consumed as a byte stream, each provider's own delta format (e.g. Anthropic's content_block_delta events) is parsed as it arrives, and each extracted text fragment is forwarded to the UI immediately as its own event, rather than waiting to assemble a complete response first.

That streaming behavior is the product, not an implementation footnote. During a live call, perceived latency is what the user experiences — they're reading or paraphrasing the suggestion out loud within seconds, so time-to-first-token is the metric that matters. A blocking call that returned a perfect, complete answer two seconds later would be a worse product than a streamed one whose first line lands in a few hundred milliseconds.

Why a native desktop app, not a browser tab

The pipeline above couldn't run in a browser tab, for specific reasons, not aesthetic ones.

A single window transforms in place between a full setup view and a compact hint panel — no second window, no second tab. That panel needs a global hotkey that works while the user's focus is inside the call app (Zoom, Meet, Teams). A browser tab can't register a truly global hotkey or react while unfocused; a native app can, and for a tool used while your attention is on the interviewer, that's not optional.

There's also an optional setting to keep the hint panel out of the user's own screen-capture or recording stream, using native window-level APIs on each platform. It's off by default and framed entirely around the user's own screen and their own choice to share it — a browser tab has no comparable control over whether it appears in the user's own capture stream.

Closing

That's the whole path: a system-audio tap (CoreAudio Process Tap on macOS, WASAPI loopback on Windows) → RMS-based segmentation → local whisper.cpp transcription (Metal / Vulkan) → a streamed response from the user's own LLM, with no server of mine anywhere in it. The specifics — the aggregate-device wrapper, the polling loopback loop, the 0.006 silence threshold, the 25-seconds-to-330ms Vulkan fix — are the honest shape of building something that has to answer within the few seconds a live interview gives you.

Happy to go deeper on any part of this in the comments — the WASAPI polling-vs-event-driven tradeoff and the macOS aggregate-device wrapper are the two I'd most enjoy discussing.

Original piece, with a network-traffic verification page for the "no backend" claim: https://syntaxcue.com/how-syntaxcue-captures-system-audio/

How I Built a Chase Bank PDF Parser with 99% Accuracy

Baurzhan Zhetenov — Thu, 20 Nov 2025 03:36:48 +0000

Parsing PDFs sounds easy until you try parsing bank statements.

I learned this the hard way.

I spent nearly 2 months building a Chase Bank PDF parser that reaches 99% accuracy across 23 real statements (1,123 transactions total). Meanwhile, generic converters like Tabula or PDFTables only hit ~70% on the same documents.

Here’s why Chase PDFs are much harder than you think—and how I solved the problems using TypeScript and pdfjs-dist, with real code you can copy.

⸻

Introduction

If you’ve ever worked with U.S. banking data, you know that Chase Bank does something strange:
They only let you download the last 18 months of transactions as CSV.

CPAs, bookkeepers, and backend engineers quickly hit a wall when they need 5+ years of historical data. Chase provides those older statements only as PDFs—and the PDFs are absolutely not designed for machine parsing.

Most accountants spend 45–60 minutes manually retyping each statement into QuickBooks or Excel.

Most developers try using generic PDF converters… and then discover that bank statements are in the top 1% of “PDFs that look structured but absolutely aren’t.”

I wanted to solve this in code.

In this article, you’ll learn:
• Why Chase PDFs are so uniquely hard to parse
• How structure-based format detection beats year-based detection
• How to infer column positions when the PDF has no headers
• How to merge split dates from fragmented PDF text items
• Real TypeScript code using pdfjs-dist
• Accuracy results from 23 real PDFs (2015–2025)

This is the article I wish existed before I started.

⸻

Part 1: Why Generic PDF Converters Fail on Bank Statements

After testing every major converter (PDFTables, Tabula, SmallPDF), I discovered four structural issues that make Chase PDFs uniquely problematic.

Let’s break them down.

⸻

Challenge 1: Multiple formats inside the SAME year

Chase used two formats simultaneously in 2024:
• v2 (2018–2024)
• v3 (2024–2025)

That means this detection method:

// ❌ WRONG: Year-based detection (breaks in 2024!)
function detectFormatWrong(year: number): 'v1' | 'v2' | 'v3' {
if (year < 2018) return 'v1';
if (year < 2024) return 'v2';
return 'v3';
}

…works fine until you get a February 2024 statement in v2 format and a May 2024 statement in v3 format.

Generic converters assume document consistency.
Chase does not.

⸻

Challenge 2: Missing column headers

Some Chase PDFs—especially early-2022 Business Checking—contain no column labels at all.

Just raw rows:

02/01 AMAZON PAYMENT $1,250.00 $15,840.32

No:
• DATE
• DESCRIPTION
• AMOUNT
• BALANCE

Generic table extractors rely on headers. Without them, they completely collapse.

⸻

Challenge 3: Variable column positions

Typical fixed-width parsers assume:

DATE DESC AMOUNT BALANCE

But Chase PDFs vary:
• DATE X position: anywhere from 30 to 70 pixels
• AMOUNT column: sometimes 2nd from right, sometimes 3rd
• BALANCE column: right-aligned but with different indentation per statement
• DESCRIPTION: can shift 40–80 pixels depending on layout

You cannot rely on static pixel positions. You must infer structure dynamically.

⸻

Challenge 4: Split dates across text items

PDF.js may return:

"0"
"2"
"/01"

instead of one "02/01".

Why?

Because Chase stores each glyph separately in the PDF.
Generic converters treat these as separate columns and produce output like:

0, 2, /01, AMAZON, PAYMENT, $1250.00

When fixed:

02/01, AMAZON PAYMENT, $1250.00

⸻

Real example:

❌ Generic PDF converter:
Row 1: 0, 2, /01, AMAZON PAYMENT, $1,250.00, ???

✅ After merging + heuristics:
Row 1: 02/01, AMAZON PAYMENT, $1,250.00, $15,840.32

⸻

Accuracy comparison (23 real PDFs):

Tool Accuracy Correct Wrong
Generic converters ~70% 802 321
Custom parser (pdfjs + TS) 99% 1,112 11

That’s 310 fewer errors—per 23 statements.

⸻

Part 2: Solution — Structure-Based Format Detection

The key insight:

Don’t detect PDF format by year. Detect it by TEXT SIGNATURES.

Chase formats have unique structural markers.
Once you read the full extracted text, you can reliably detect formats.

⸻

The 3 Chase formats

Format Years Columns Structure Unique Signature
v1 2015–2017 3 cols Simple list No section headers
v2 2018–2024 4 cols Transaction table "TRANSACTION DETAIL"
v3 2024–2025 3 cols Grouped by category "DEPOSITS AND ADDITIONS" + "TOTAL DEPOSITS"

⸻

Year-based detection (WRONG)

// ❌ breaks immediately in 2024
function detectFormatWrong(year: number): 'v1' | 'v2' | 'v3' {
if (year < 2018) return 'v1';
if (year < 2024) return 'v2';
return 'v3';
}

⸻

Structure-based detection (CORRECT)

// ✅ CORRECT: Structure-based detection
function detectChaseFormat(fullText: string): 'v1' | 'v2' | 'v3' {
// Priority 1: Check for v2 signature
if (fullText.includes('TRANSACTION DETAIL')) {
return 'v2';
}

// Priority 2: Check for v3 signature
if (fullText.includes('DEPOSITS AND ADDITIONS') &&
fullText.includes('TOTAL DEPOSITS')) {
return 'v3';
}

// Priority 3: Year-based fallback for old v1 format
const year = extractStatementYear(fullText);
if (year && year < 2018) {
return 'v1';
}

// Default: assume v2
return 'v2';
}

⸻

Why this works
• v2 always includes "TRANSACTION DETAIL"
• v3 always includes "DEPOSITS AND ADDITIONS" and "TOTAL DEPOSITS"
• v1 has none of these markers, so year fallback is safe
• Adding future formats becomes trivial: just add new signatures at top of the list

⸻

Real-world validation

I tested all 23 PDFs:
• v1: 1 file
• v2: 15 files
• v3: 7 files

Detection accuracy: 23/23 (100%).

This approach also works for:
• Business Checking
• Personal Banking
• PDFs during format transition periods (e.g., April–July 2024)

⸻

Part 3: Heuristic Column Detection for PDFs with NO Headers

Some Chase PDFs simply omit headers altogether.
You must infer columns dynamically.

The solution:

Infer column positions from the first transaction row using date heuristics.

⸻

Step-by-step algorithm

Identify first transaction using date pattern
• Look for MM/DD (02/01)
• In X range 30–70 (Chase always puts dates on left)
Extract all text items on the same horizontal row

Use Y coordinate tolerance of ±5px.

Sort items left-to-right by X
Infer column meaning:
• leftmost → date
• center → description
• 2nd from right → amount
• rightmost → balance

These rules held across every tested statement.

⸻

Code: Column detection

interface ColumnPositions {
dateX: number;
descX: number;
amountX: number;
balanceX: number;
}

function inferColumnPositions(
textItems: PDFTextItem[]
): ColumnPositions {
// Step 1: Find the first transaction row
const firstDateItem = textItems.find(item =>
/^\d{2}\/\d{2}$/.test(item.str) &&

item.transform[4] >= 30 &&

item.transform[4] <= 70

);

if (!firstDateItem) {
throw new Error('Cannot find first transaction (no date pattern found)');
}

// Step 2: Extract row by Y position
const dateY = firstDateItem.transform[5];
const rowItems = textItems.filter(item =>
Math.abs(item.transform[5] - dateY) < 5
);

// Step 3: Sort left-to-right
const sortedByX = rowItems.sort((a, b) =>
a.transform[4] - b.transform[4]
);

// Step 4: Infer from positions
return {
dateX: sortedByX[0].transform[4],
descX: (sortedByX[0].transform[4] +
sortedByX[sortedByX.length - 1].transform[4]) / 2,
balanceX: sortedByX[sortedByX.length - 1].transform[4],
amountX: sortedByX[sortedByX.length - 2].transform[4]
};
}

⸻

Why this works
• Chase PDFs ALWAYS have date on the far left
• Balance is ALWAYS right-aligned
• Description always occupies the middle
• Amount is consistently next to balance

This works even with:
• v1 (3 columns)
• v2 (4 columns)
• v3 (3 columns + grouped sections)

⸻

Part 4: Handling Split Dates

pdfjs-dist often splits glyphs into separate items.

Example raw output:

"0"
"2"
"/"
"0"
"1"

You must merge items by proximity.

⸻

Core idea:

If two items’ X positions differ < 15px, they’re part of the same text value.

This was empirically tested across 23 PDFs.

⸻

Code: Merging split date fragments

function mergeSplitDates(items: PDFTextItem[]): PDFTextItem[] {
const merged: PDFTextItem[] = [];
let buffer = '';
let bufferX = 0;

for (let i = 0; i < items.length; i++) {
const item = items[i];
const nextItem = items[i + 1];

// Merge if close enough
if (nextItem &&
    Math.abs(nextItem.transform[4] - item.transform[4]) < 15) {
  buffer += item.str;
  if (!bufferX) bufferX = item.transform[4];
} else {
  merged.push({
    str: buffer + item.str,
    transform: [0, 0, 0, 0, bufferX || item.transform[4], item.transform[5]]
  });
  buffer = '';
  bufferX = 0;
}

}

return merged;
}

⸻

Why 15px?
• < 10px missed some merges
• 20px caused accidental merges
• 15px was perfect across all documents

Result

❌ Before: ["0", "2", "/01", "AMAZON", "PAY", "MENT"]
✅ After: ["02/01", "AMAZON PAYMENT"]

You absolutely cannot build a reliable parser without this.

⸻

Part 5: Tech Stack & Architecture

Here’s the stack that worked reliably.

⸻

Core technologies

pdfjs-dist
• Same engine Firefox uses
• Extracts precise text positions (X/Y)
• Supports PDF 1.4–2.0
• Lightweight compared to OCR (no 200MB Tesseract install)

TypeScript
• Needed for complex PDF item types
• Prevents 90% of runtime errors
• Great autocomplete for pdfjs API

Node.js
• Fast enough for server-side parsing
• Can run heavy parsing without blocking UI

Bull + Redis
• Parallel PDF processing
• Retry logic
• Failure handling that generic HTTP handlers lack

ExcelJS
• Generates QuickBooks-ready Excel output
• Supports proper data validation + number formats

⸻

System Architecture Flow

User uploads PDF
↓
Backend creates Bull job
↓
Worker parses PDF with pdfjs-dist
↓
Detect format (v1/v2/v3)
↓
Merge split dates
↓
Infer column positions
↓
Extract rows into normalized structure
↓
Generate final Excel file (ExcelJS)
↓
Return download URL

⸻

Performance
• Average PDF: 5 seconds
• Largest tested PDF (273 transactions): 2 seconds
• Bottleneck: Excel generation, not PDF parsing

⸻

Part 6: Results & Lessons Learned

I tested the parser on a dataset of 23 real Chase PDF statements:
• Business + Personal
• 2015–2025 (10 years)
• Formats: v1, v2, v3
• Total rows: 1,123 transactions

⸻

Accuracy

Metric Generic Tools Custom Parser
Correct Transactions 802 1,112
Format Detection 33% 100%
Headerless PDFs Fail Pass
Split Date Handling Fail Pass
Total Accuracy ~71% 99%

⸻

What Worked

✔ Structure-based detection
✔ Heuristic column inference
✔ Split date merging
✔ Real-world testing (not synthetic PDFs)
✔ Using pdfjs-dist instead of OCR or regex-heavy hacks

⸻

What Didn’t Work

❌ Regex-only parsing
❌ Assuming headers always exist
❌ Fixed column positions
❌ Year-based format detection
❌ OCR — slow, inaccurate, unnecessary

⸻

Key Lessons Learned

Test with real documents

Not all PDFs behave the same.

Structure > content

Detect formats by text signatures, not by year.

Use tolerance ranges, not precise numbers

Between PDFs, text shifts significantly.

Merge text items aggressively

PDF.js fragments everything.

Don’t try to “regex your way out”

Positional parsing beats text scrubbing every time.

⸻

Conclusion

Building a Chase Bank PDF parser taught me something unexpected:

PDFs are simple to read as humans and extremely complex to parse as machines.

Chase statements, in particular, combine:
• Multiple formats in the same year
• Missing headers
• Variable column alignment
• Fragmented text items

Generic converters assume too much structure.
To reach production-grade accuracy, you must infer structure dynamically.

The winning combination was:
• Structure-based format detection
• Heuristic column detection
• Split date merging
• pdfjs-dist + TypeScript
• Extensive testing on real PDFs

If you’re working with Chase PDFs and want to try a ready-made implementation, you can use https://bank-parser.com/?utm_source=devto&utm_medium=article&utm_campaign=tutorial_pdf (free trial, no card required).

Have you built PDF parsers before?
What challenges did you face? I’d love to hear what approaches worked (or failed!) for you — share in the comments!