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

## 📋 Pull Request Information **Original PR:** https://github.com/CCExtractor/ccextractor/pull/1885 **Author:** [@x15sr71](https://github.com/x15sr71) **Created:** 12/23/2025 **Status:** 🔄 Open **Base:** `master` ← **Head:** `feat/ssa-ass-precise-positioning` --- ### 📝 Commits (8) - [`5dd1961`](https://github.com/CCExtractor/ccextractor/commit/5dd19612b1417a7cf604fedee733f700707906d6) feat(ssa): add guarded ASS \pos positioning for CEA-608 captions - [`a742174`](https://github.com/CCExtractor/ccextractor/commit/a74217413954f1aa157282b8195b8f7131d4c357) Merge branch 'master' into feat/ssa-ass-precise-positioning - [`140bff3`](https://github.com/CCExtractor/ccextractor/commit/140bff309f51e33d39f7405a0eb85fa5b6b4f9a2) fix(ssa): correct ASS positioning anchor, validate row adjacency, and clean up variable placement - [`ac22206`](https://github.com/CCExtractor/ccextractor/commit/ac222065463760066857351753d058693d68821a) docs(changelog): move SSA entry to correct section - [`4f6a832`](https://github.com/CCExtractor/ccextractor/commit/4f6a83246a460edaddac5a25ae6603308ef4a6b1) ssa: minor cleanup of loop variables (no behavior change) - [`80d253d`](https://github.com/CCExtractor/ccextractor/commit/80d253db9b079c5614143d812e38ab3eebb80dd6) fix(ssa): adjust top margin to prevent clipping of top-positioned CEA-608 captions - [`2294dd4`](https://github.com/CCExtractor/ccextractor/commit/2294dd4ce4fa78c4b8f60880969b7c886d575a93) Merge branch 'master' into feat/ssa-ass-precise-positioning - [`a9caddd`](https://github.com/CCExtractor/ccextractor/commit/a9cadddfd83130eba0e2d6afa9dc8e1fbd4c432a) Update CHANGES.TXT for version 0.96.6 ### 📊 Changes **3 files changed** (+90 additions, -0 deletions) <details> <summary>View changed files</summary> 📝 `docs/CHANGES.TXT` (+1 -0) 📝 `src/lib_ccx/ccx_encoders_common.c` (+2 -0) 📝 `src/lib_ccx/ccx_encoders_ssa.c` (+87 -0) </details> ### 📄 Description  **In raising this pull request, I confirm the following (please check boxes):** - [X] I have read and understood the [contributors guide](https://github.com/CCExtractor/ccextractor/blob/master/.github/CONTRIBUTING.md). - [X] I have checked that another pull request for this purpose does not exist. - [X] I have considered, and confirmed that this submission will be valuable to others. - [X] I accept that this submission may not be used, and the pull request closed at the will of the maintainer. - [X] I give this submission freely, and claim no ownership to its content. - [X] **I have mentioned this change in the [changelog](https://github.com/CCExtractor/ccextractor/blob/master/docs/CHANGES.TXT).** **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. - [X] I am an active contributor to CCExtractor. --- ## [FEATURE] - Add ASS/SSA \pos positioning for CEA-608 captions ([feature request #1726](https://github.com/CCExtractor/ccextractor/issues/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](https://sampleplatform.ccextractor.org/sample/56c9f345482c635f20340d13001f1083a7c1913c787075d6055c112fe8e2fcaa) from the [CCExtractor sample platform](https://sampleplatform.ccextractor.org/sample/): - Comparison of output: [Before.ass](https://drive.google.com/file/d/17RUhC420OsIYNN-mjR_TcVByIpORFtrS/view?usp=sharing) → [After.ass](https://drive.google.com/file/d/13-DKbiaG5zbOsl40cs2reBgt3hiH3x2q/view?usp=sharing) - 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. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

claunia commented

2026-01-29 17:23:22 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/CCExtractor/ccextractor/pull/1885
Author: @x15sr71
Created: 12/23/2025
Status: 🔄 Open

Base: master ← Head: feat/ssa-ass-precise-positioning

📝 Commits (8)

5dd1961 feat(ssa): add guarded ASS \pos positioning for CEA-608 captions
a742174 Merge branch 'master' into feat/ssa-ass-precise-positioning
140bff3 fix(ssa): correct ASS positioning anchor, validate row adjacency, and clean up variable placement
ac22206 docs(changelog): move SSA entry to correct section
4f6a832 ssa: minor cleanup of loop variables (no behavior change)
80d253d fix(ssa): adjust top margin to prevent clipping of top-positioned CEA-608 captions
2294dd4 Merge branch 'master' into feat/ssa-ass-precise-positioning
a9caddd Update CHANGES.TXT for version 0.96.6

📊 Changes

3 files changed (+90 additions, -0 deletions)

View changed files

📝 docs/CHANGES.TXT (+1 -0)
📝 src/lib_ccx/ccx_encoders_common.c (+2 -0)
📝 src/lib_ccx/ccx_encoders_ssa.c (+87 -0)

📄 Description

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.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

claunia added the pull-request label 2026-01-29 17:23:22 +00:00

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