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

[cfsmp3]

The implementation looks good! The positioning is working correctly and the guard for 1-2 row captions is a sensible approach to avoid regressions.

The Windows CI failure is expected since the ASS output format changed - we'll need to update the test baselines.

One small fix needed: the CHANGES.TXT entry appears incomplete:

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

Please complete this sentence (e.g., "...when layout information is available" or similar).

Once that's fixed, we can merge and update the test baselines.

[x15sr71]

@cfsmp3, I've completed the CHANGES.TXT entry as discussed and resolved the merge conflict by keeping both entries. Please let me know if anything else needs adjustment.

[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 9a76133...:

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 --ucla dab1c1bd65..., Last passed: Never
• ccextractor --out=srt --latin1 --autoprogram 29e5ffd34b..., 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 passed completely.

Check the result page for more info.

[ccextractor-bot]

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

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

Your PR breaks these cases:

• ccextractor --autoprogram --out=srt --latin1 --quant 0 85271be4d2...
• ccextractor --autoprogram --out=ttxt --latin1 --ucla dab1c1bd65...
• ccextractor --out=srt --latin1 --autoprogram 29e5ffd34b...
• ccextractor --out=spupng c83f765c66...
• ccextractor --startcreditstext "CCextractor Start crdit Testing" c4dd893cb9...
• ccextractor --startcreditsnotbefore 1 --startcreditstext "CCextractor Start crdit Testing" c4dd893cb9...
• ccextractor --startcreditsnotafter 2 --startcreditstext "CCextractor Start crdit Testing" c4dd893cb9...
• ccextractor --startcreditsforatleast 1 --startcreditstext "CCextractor Start crdit Testing" c4dd893cb9...
• ccextractor --startcreditsforatmost 2 --startcreditstext "CCextractor Start crdit Testing" c4dd893cb9...

It seems that not all tests were passed completely. This is an indication that the output of some files is not as expected (but might be according to you).

Check the result page for more info.