PDFium: word tracking and speech cursoring in Delphi

Delphi ve C++Builder uygulamalarına PDFium VCL Component iş akışlarını, Lazarus/FPC projelerine PDFium LCL Component iş akışlarını; görüntüleme, render, formlar, yazdırma, preflight raporları ve standart odaklı doğrulama için kaynak kodlu bileşenlerle ekleyin.

Bu yazı developers building read-aloud, study, review, or assisted-reading features in Delphi PDF viewers için hazırlanmıştır. word tracking and speech cursoring konusunu tek bir bileşen çağrısı olarak değil, üretim düzeyinde belge mühendisliği olarak ele alır.

Pratik risk şudur: speech highlighting becomes distracting or wrong when word boxes, ligatures, rotation, hidden text, and timing do not match the spoken stream. Bu nedenle akışın yazılı sözleşmeye, gözlemlenebilir tanılara ve gerçekçi regresyon dosyalarına ihtiyacı vardır.

Mimari kararlar

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

Uygulama akışı

Track words through a stable text map. Aşağıdaki sıra, iş akışını Delphi ve C++Builder ekipleri için incelenebilir tutar.

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

Doğrulama kanıtı

Synchronization evidence for assisted reading. Bu alanları çıktı veya destek kaydıyla birlikte saklayın.

• 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?

Mühendislik inceleme notları: word tracking and speech cursoring

Özelliğin bir demoyu aşıp sürüm, destek ve müşteri eskalasyonu sırasında savunulabilir olduğunu doğrulamak için bu inceleme notlarını kullanın.

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

Sınır durumları

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

Delphi kod örneği

Aşağıdaki Delphi taslağı bu konu için pratik bir servis sınırını gösterir. Politika kontrollerini, günlüklemeyi ve doğrulamayı dar ürün çağrısı bölümünün dışında tutarak akışı test edilebilir bırakın.

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;

Üretim kontrol listesi

• İş akışını boş bir dosyada, normal bir müşteri dosyasında ve en kötü durum dosyasında çalıştırın
• Oluşturulan PDF'yi hedef görüntüleyici, doğrulayıcı, yazıcı veya aşağı akış uygulamasıyla açın
• Ürün sürümünü, profil sürümünü, giriş karmasını, çıktı yolunu, geçen süreyi ve uyarı sayısını kaydedin
• Parolaları, sertifikaları, geçici dosyaları ve müşteri verilerini açık saklama kuralları altında tutun
• Bir müşteri dosyası yeni bir uç durum ortaya çıkardığında regresyon belgeleri ekleyin

Ürün belgeleri

PDFium Component

Ek kod örnekleri

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;