[FEATURE] Add guarded ASS/SSA \pos positioning for CEA-608 captions

[x15sr71]

In raising this pull request, I confirm the following (please check boxes):

• I have read and understood the contributors guide.
• I have checked that another pull request for this purpose does not exist.
• I have considered, and confirmed that this submission will be valuable to others.
• I accept that this submission may not be used, and the pull request closed at the will of the maintainer.
• I give this submission freely, and claim no ownership to its content.
• I have mentioned this change in the changelog.

My familiarity with the project is as follows (check one):

• I have never used CCExtractor.
• I have used CCExtractor just a couple of times.
• I absolutely love CCExtractor, but have not contributed previously.
• I am an active contributor to CCExtractor.

---

[FEATURE] - Add ASS/SSA \pos positioning for CEA-608 captions (feature request #1726)

Summary

Implements precise positioning for ASS/SSA subtitle export using \pos(x,y) tags, replacing whitespace-based layout where sufficient positioning information is available.

Fixes #1726

Changes

• Added ass_position_from_row() function to map CEA-608 rows to ASS coordinates
• Applied {\an2\pos(x,y)} positioning tags for single-region captions (1-2 rows)
• Added PlayResX/PlayResY declarations to Script Info header (384×288)
• Maintained backward compatibility via conservative guards

Design Decisions

Positioning is intentionally conservative:

• Applied only when 1-2 caption rows are active to avoid layout conflicts
• Mapped to lower-third region (60-95% of PlayResY) to preserve readability and
  avoid unsafe display areas
• Falls back to legacy whitespace behavior when layout is ambiguous (>2 rows)

Resolution choice:

• Uses SSA default 384×288 resolution (standard for libass/Aegisub/VSFilter)
• Now explicitly declared in header for spec compliance

This improves visual consistency without changing caption semantics or risking regressions on complex roll-up layouts.

Testing

• Verified output using a sample from the CCExtractor sample platform:
• Comparison of output: Before.ass → After.ass
• Position tags correctly map CEA-608 rows into lower-third ASS coordinates
• Legacy SSA whitespace-based layout is preserved for multi-region captions

Future Enhancements

Fuller grid-based positioning and horizontal placement derived from CEA-608 semantics; however, this involves additional
interpretation of PAC data and roll-up behavior and is intentionally out of scope for this change.

[cfsmp3]

Review Summary

Thanks for this feature! The implementation is well-designed with good safeguards. Testing confirms it works correctly.

✅ What's Good

• Conservative guard: only applies positioning for 1-2 row captions
• Falls back gracefully to legacy behavior for complex layouts (>2 rows)
• Uses standard SSA resolution (384×288) with explicit header declaration
• Positioning math is correct: Row 0 → y=172 (60%), Row 14 → y=273 (95%)
• Doesn't affect SRT or other output formats
• All CI checks pass, all 248 Rust tests pass

Testing Results

Tested with sample 56c9f345... from Sample Platform:

• 118 dialogues correctly received {\an2\pos(x,y)} tags
• 1 dialogue with >2 rows correctly fell back to legacy behavior
• Compared with master: changes are purely additive

📋 One Minor Fix Needed

CHANGES.TXT entry is truncated:

- New: Added ASS/SSA \pos-based positioning for CEA-608 captions when layout

Please complete the sentence, e.g.:

- New: Added ASS/SSA \pos-based positioning for CEA-608 captions when layout is simple (1-2 rows) (#1726)

Once fixed, this is ready to merge! 🎉

[cfsmp3]

Note: The approval above is conditional on the Sample Platform CI tests passing. The tests were still queued at the time of review:

• CI - linux: pending
• CI - windows: pending

Please wait for these to complete before merging. If any tests fail, the issues should be addressed first.

[x15sr71]

Thanks for the review. I’ve fixed the truncated changelog entry and updated the loops to use scoped variables, and pushed the updated commit.

[ccextractor-bot]

CCExtractor CI platform finished running the test files on linux. Below is a summary of the test results, when compared to test for commit d573548...:

Report Name	Tests Passed
Broken	13/13
CEA-708	14/14
DVB	7/7
DVD	3/3
DVR-MS	2/2
General	27/27
Hardsubx	1/1
Hauppage	3/3
MP4	3/3
NoCC	10/10
Options	86/86
Teletext	21/21
WTV	13/13
XDS	34/34

Congratulations: Merging this PR would fix the following tests:

• ccextractor --autoprogram --out=ttxt --latin1 1974a299f0..., Last passed: Never
• ccextractor --autoprogram --out=ttxt --latin1 --ucla dab1c1bd65..., Last passed: Never
• ccextractor --out=srt --latin1 --autoprogram 29e5ffd34b..., Last passed: Never
• ccextractor --xdsdebug --out=srt c83f765c66..., Last passed: Never
• ccextractor --startcreditstext "CCextractor Start crdit Testing" c4dd893cb9..., Last passed: Never
• ccextractor --startcreditsnotbefore 1 --startcreditstext "CCextractor Start crdit Testing" c4dd893cb9..., Last passed: Never
• ccextractor --startcreditsnotafter 2 --startcreditstext "CCextractor Start crdit Testing" c4dd893cb9..., Last passed: Never
• ccextractor --startcreditsforatleast 1 --startcreditstext "CCextractor Start crdit Testing" c4dd893cb9..., Last passed: Never
• ccextractor --startcreditsforatmost 2 --startcreditstext "CCextractor Start crdit Testing" c4dd893cb9..., Last passed: Never

All tests passing on the master branch were passed completely.

Check the result page for more info.