PDFium: word tracking and speech cursoring in Delphi

Integruj workflow PDFium VCL Component w aplikacjach Delphi i C++Builder albo workflow PDFium LCL Component w Lazarus/FPC, z komponentami źródłowymi do podglądu, renderowania, formularzy, drukowania, raportów preflight i walidacji zgodnej ze standardami.

Ten artykuł jest przeznaczony dla developers building read-aloud, study, review, or assisted-reading features in Delphi PDF viewers. Traktuje word tracking and speech cursoring jako produkcyjną inżynierię dokumentów, a nie pojedyncze wywołanie komponentu.

Praktyczne ryzyko polega na tym, że speech highlighting becomes distracting or wrong when word boxes, ligatures, rotation, hidden text, and timing do not match the spoken stream. Dlatego przepływ wymaga spisanego kontraktu, obserwowalnej diagnostyki i realistycznych plików regresyjnych.

Decyzje architektoniczne

Synchronize speech with extracted text, not pixels alone. text extraction source, word segmentation policy, and language assumptions / highlight style, scroll behavior, pause and resume rules, and user controls

• text extraction source, word segmentation policy, and language assumptions
• highlight style, scroll behavior, pause and resume rules, and user controls
• fallback behavior for image-only pages, hidden text, ligatures, and rotated content
• whether speech timing is driven by the engine, the viewer, or a shared coordinator

Przebieg implementacji

Track words through a stable text map. Poniższa kolejność zachowuje czytelność przepływu pracy dla zespołów Delphi i C++Builder.

1. extract page text and word bounds before speech playback begins
2. build a word map that links text offsets, page numbers, and viewer coordinates
3. call the tracking layer as the speech engine advances through words or offsets
4. scroll the viewport only when the current word leaves the comfortable reading zone
5. record skipped words, missing boxes, and timing drift for diagnostics

Dowody walidacji

Synchronization evidence for assisted reading. Zachowaj te pola wraz z wynikiem lub rekordem wsparcia.

• page number, word text, text offset, bounding box, and speech timestamp
• tracking method used, including TrackReadingWordAt when the viewer supports it
• fallback reason for words without reliable geometry
• latency between speech event and visible cursor update

Word boxes are viewer data

Word-synchronized reading needs a mapping between extracted text, page coordinates, and speech timing. A robust implementation knows when text is unavailable, when a word box is ambiguous, and how to keep the viewport aligned with the current spoken word.

Review questions before release

Before this reaches production, the team should be able to answer these questions without reading source code.

• Who owns text extraction source, word segmentation policy, and language assumptions?
• What evidence proves page number, word text, text offset, bounding box, and speech timestamp?
• What happens when ligatures can represent multiple characters inside one visual glyph?
• Which regression file covers record skipped words, missing boxes, and timing drift for diagnostics?

Notatki przeglądu inżynierskiego dla word tracking and speech cursoring

Użyj tych notatek przeglądu, aby upewnić się, że funkcja wyszła poza demonstrację i da się ją obronić podczas wydania, wsparcia i eskalacji klienta.

• Decyzja: text extraction source, word segmentation policy, and language assumptions. Punkt nacisku implementacji: build a word map that links text offsets, page numbers, and viewer coordinates. Dowody akceptacji: fallback reason for words without reliable geometry. Wyzwalacz regresji: rapid speech rates can require coalescing highlight updates to avoid flicker
• Decyzja: highlight style, scroll behavior, pause and resume rules, and user controls. Punkt nacisku implementacji: call the tracking layer as the speech engine advances through words or offsets. Dowody akceptacji: latency between speech event and visible cursor update. Wyzwalacz regresji: ligatures can represent multiple characters inside one visual glyph
• Decyzja: fallback behavior for image-only pages, hidden text, ligatures, and rotated content. Punkt nacisku implementacji: scroll the viewport only when the current word leaves the comfortable reading zone. Dowody akceptacji: page number, word text, text offset, bounding box, and speech timestamp. Wyzwalacz regresji: rotated or vertical text needs coordinate handling separate from normal pages

Przypadki brzegowe

• ligatures can represent multiple characters inside one visual glyph
• rotated or vertical text needs coordinate handling separate from normal pages
• OCR text layers may not align perfectly with scanned images
• rapid speech rates can require coalescing highlight updates to avoid flicker

Delphi / C++Builder notes

PDFium Component should sit behind a small service boundary that receives files, streams, profiles, and credentials, then returns output paths, warnings, metrics, and validation status. Important terms include TrackReadingWordAt, speech cursor, word bounds, text extraction, highlight, reading assistance.

Przykład kodu Delphi

Poniższy szkic Delphi pokazuje praktyczną granicę usługi dla tego tematu. Kontrole zasad, logowanie i walidację trzymaj poza wąskim blokiem wywołań produktu, aby przepływ pozostał testowalny.

procedure TSpeechForm.SpeakWordAtCursor(PageNo, CharIndex: Integer);
var
  UnitInfo: TReadingUnit;
begin
  UnitInfo := LocateWordUnit(PdfView, PageNo, CharIndex);
  HighlightBounds(UnitInfo.PageNo, UnitInfo.Bounds);
  SpeechQueue.Speak(UnitInfo.Text);
  StoreCursorPosition(UnitInfo.PageNo, UnitInfo.EndChar);
end;

Lista produkcyjna

• Uruchom przepływ pracy na pustym pliku, zwykłym pliku klienta i pliku z najgorszego scenariusza
• Otwórz wygenerowany plik PDF w docelowej przeglądarce, walidatorze, drukarce lub aplikacji nadrzędnej
• Zaloguj wersję produktu, wersję profilu, hash wejścia, ścieżkę wyjścia, czas wykonania i liczbę ostrzeżeń
• Przechowuj hasła, certyfikaty, pliki tymczasowe i dane klienta zgodnie z jednoznacznymi zasadami retencji
• Dodaj dokument regresyjny, gdy plik klienta ujawni nowy przypadek brzegowy

Dokumentacja produktu

PDFium Component

Dodatkowe przykłady kodu

procedure TReaderForm.OnSpeechWordBoundary(StreamPos: Integer);
var
  WordIdx: Integer;
begin
  // Maps the offset to a word box and moves the highlight in one call
  WordIdx := PdfView.TrackReadingWordAt(FPageNo, StreamPos);
  if WordIdx < 0 then
    Exit;                     // boundary fell outside any word: keep last highlight
end;

procedure TReaderForm.StopReading;
begin
  FVoice.Stop;                // halt SAPI playback first
  PdfView.ClearReadingWord;   // then remove the highlight; a stale cursor reads as a bug
end;