From b1d2d958eebfb5cb13cfbeae2d66a8ef977ed249 Mon Sep 17 00:00:00 2001
From: OlteanuRares <rares.olteanu@3pillarglobal.com>
Date: Wed, 22 Jul 2026 10:13:07 +0300
Subject: [PATCH] OCTO-11510 Split monolithic pycaption/sami.py into
 pycaption/sami/ package   (constants, parser, reader, writer). Emit VTT  as
 class   attribute instead of leaking into inline CSS, add text-align from  
 Layout alignment, produce valid stylesheet rules for VTT class styles,  
 filter non-CSS keys, silently drop writing direction. Fix rules-dict  
 mutation in _recreate_style_block, inline dead hooks, add docstrings.

---
 docs/changelog.rst            |   8 +
 pycaption/sami.py             | 809 ----------------------------------
 pycaption/sami/__init__.py    |   4 +
 pycaption/sami/constants.py   |  23 +
 pycaption/sami/parser.py      | 179 ++++++++
 pycaption/sami/reader.py      | 314 +++++++++++++
 pycaption/sami/writer.py      | 267 +++++++++++
 tests/test_sami_conversion.py |  98 +++-
 8 files changed, 889 insertions(+), 813 deletions(-)
 delete mode 100644 pycaption/sami.py
 create mode 100644 pycaption/sami/__init__.py
 create mode 100644 pycaption/sami/constants.py
 create mode 100644 pycaption/sami/parser.py
 create mode 100644 pycaption/sami/reader.py
 create mode 100644 pycaption/sami/writer.py

diff --git a/docs/changelog.rst b/docs/changelog.rst
index a2f5de41..ff2013d9 100644
--- a/docs/changelog.rst
+++ b/docs/changelog.rst
@@ -22,6 +22,14 @@ Changelog
   - Split pycaption/dfxp/ into constants.py, reader.py, writer.py
     (same pattern as scc/ and webvtt/). Public API unchanged —
     ``__init__.py`` re-exports all symbols.
+  - SAMI writer: align with WebVTT reader's structured output — emit
+    ``classes`` as ``class=`` attribute (not inline CSS), emit text-align
+    from Layout, produce valid CSS in stylesheet for VTT class styles,
+    filter non-CSS keys (webvtt_positioning, writing_direction), silently
+    drop writing direction (SAMI has no writing-mode).
+  - Split pycaption/sami.py into pycaption/sami/ package. Public API
+    unchanged. Reader: inline dead hooks, extract helpers, add docstrings.
+    Writer: fix rules-dict mutation, remove dead ``_encode``, staticmethods.
 
 2.2.28
 ^^^^^^
diff --git a/pycaption/sami.py b/pycaption/sami.py
deleted file mode 100644
index 078acb71..00000000
--- a/pycaption/sami.py
+++ /dev/null
@@ -1,809 +0,0 @@
-"""
-The classes in this module handle SAMI reading and writing. It supports several
-CSS attributes, some of which are handled as positioning settings (and applied
-to Layout objects) and others as simple styling (applied to legacy style nodes).
-
-The following attributes are handled as positioning:
-
-    'text-align' # Converted to Alignment
-    'margin-top'
-    'margin-right'
-    'margin-bottom'
-    'margin-left'
-
-OBS:
-    * Margins are converted to Padding
-    * Margins defined inline are not supported
-      TODO: Add support for inline margins
-
-Any other CSS the BeautifulSoup library manages to parse is handled as simple
-styling and applied to style nodes. However, apparently only these are actually
-used by writers on conversion:
-
-    'font-family'
-    'font-size'
-    'font-style'
-    'color'
-OBS:
-    * Other parameters are preserved, but not if they're specified inline.
-    TODO:
-      Make this less confusing. Confirm whether these really are the only
-      supported styling attributes and make it more clear, perhaps by listing
-      them in constants in the beginning of the file and using them to filter
-      out unneeded attributes either everywhere in the code or not at all, but
-      most importantly regardless of whether they're defined inline or not,
-      because this is irrelevant.
-
-"""
-import re
-from collections import deque
-from copy import deepcopy
-from html.entities import name2codepoint
-from html.parser import HTMLParser
-from logging import FATAL
-from xml.dom import SyntaxErr
-from xml.sax.saxutils import escape
-
-from bs4 import BeautifulSoup, NavigableString
-from cssutils import css as cssutils_css
-from cssutils import log, parseString
-
-from .base import (
-    DEFAULT_LANGUAGE_CODE,
-    BaseReader,
-    BaseWriter,
-    Caption,
-    CaptionList,
-    CaptionNode,
-    CaptionSet,
-)
-from .exceptions import (
-    CaptionReadNoCaptions,
-    CaptionReadSyntaxError,
-    CaptionReadTimingError,
-    InvalidInputError,
-)
-from .geometry import Alignment, Layout, Padding, Size
-
-# change cssutils default logging
-log.setLevel(FATAL)
-
-SAMI_BASE_MARKUP = """
-<sami>
-    <head>
-        <style type="text/css"/>
-    </head>
-    <body/>
-</sami>"""
-
-
-class SAMIReader(BaseReader):
-    def __init__(self, *args, **kw):
-        super().__init__(*args, **kw)
-        self.line = []
-        self.first_alignment = None
-
-    def detect(self, content):
-        if "<sami" in content.lower():
-            return True
-        else:
-            return False
-
-    def read(self, content):
-        if not isinstance(content, str):
-            raise InvalidInputError("The content is not a unicode string.")
-
-        content, doc_styles, doc_langs = self._get_sami_parser_class()().feed(content)
-        sami_soup = self._get_xml_parser_class()(content, features="lxml")
-
-        # Get the global layout that applies to all <p> tags
-        global_layout = self._build_layout(doc_styles.get("p", {}))
-
-        caption_dict = {}
-        for language in doc_langs:
-            lang_layout = None
-            for target, styling in list(doc_styles.items()):
-                if target not in ["p", "sync", "span"]:
-                    if styling.get("lang", None) == language:
-                        lang_layout = self._build_layout(
-                            doc_styles.get(target, {}), inherit_from=global_layout
-                        )
-                        break
-            lang_layout = lang_layout or global_layout
-            lang_captions = self._translate_lang(language, sami_soup, lang_layout)
-
-            caption_dict[language] = lang_captions
-
-        caption_set = CaptionSet(caption_dict, layout_info=global_layout)
-
-        # Convert styles from CSS to internal representation
-        for style in list(doc_styles.items()):
-            style = (style[0], self._translate_parsed_style(style[1]))
-
-        caption_set.set_styles(doc_styles)
-
-        if caption_set.is_empty():
-            raise CaptionReadNoCaptions("empty caption file")
-
-        return caption_set
-
-    @staticmethod
-    def _get_sami_parser_class():
-        """Hook method for providing custom SAMIParser classes"""
-        return SAMIParser
-
-    @staticmethod
-    def _get_xml_parser_class():
-        """Hook method for providing a custom XML parser class"""
-        return BeautifulSoup
-
-    def _build_layout(self, styles, inherit_from=None):
-        """
-        :type styles: dict
-        :param styles: a dictionary with CSS-like styling rules
-
-        :type inherit_from: Layout
-        :param inherit_from: The Layout with values to be used in case the
-            positioning settings in the styles parameter don't specify
-            something.
-        """
-        alignment = Alignment.from_horizontal_and_vertical_align(
-            text_align=styles.get("text-align")
-        )
-        return self._get_layout_class()(
-            origin=None,
-            extent=None,
-            padding=self._get_padding(styles),
-            alignment=alignment,
-            inherit_from=inherit_from,
-        )
-
-    @staticmethod
-    def _get_layout_class():
-        """Hook method for providing a custom Layout class"""
-        return Layout
-
-    def _get_padding(self, styles):
-        margin_before = self._get_size(styles, "margin-top")
-        margin_after = self._get_size(styles, "margin-bottom")
-        margin_start = self._get_size(styles, "margin-left")
-        margin_end = self._get_size(styles, "margin-right")
-        if not any([margin_before, margin_after, margin_start, margin_end]):
-            return None
-        return Padding(
-            before=margin_before,  # top
-            after=margin_after,  # bottom
-            start=margin_start,  # left
-            end=margin_end,  # right
-        )
-
-    def _get_size(self, styles, style_label):
-        value_from_style = styles.get(style_label, None)
-        if not value_from_style:
-            return None
-        return Size.from_string(value_from_style)
-
-    def _translate_lang(self, language, sami_soup, parent_layout):
-        """
-        For a given language, translate the SAMI XML to internal list of
-        captions.
-
-        :rtype: list
-        """
-        captions = CaptionList(layout_info=parent_layout)
-        milliseconds = 0
-
-        for p in sami_soup.select(f"p[lang|={language}]"):
-            start_str = p.parent.get("start")
-            if not start_str:
-                raise CaptionReadTimingError(
-                    f"Missing start time on the following line: {p.parent}."
-                )
-            milliseconds = int(float(start_str))
-            start = milliseconds * 1000
-            end = 0
-
-            # Setting current start time as end time for previous elements with
-            # 0 as ending ( when we have more p elements inside a SYNC element )
-            for i in reversed(range(len(captions))):
-                if captions[i].end != 0:
-                    break
-                if captions[i].start != start:
-                    captions[i].end = start
-
-            if p.get_text().strip():
-                self.first_alignment = None
-                styles = self._translate_attrs(p)
-                layout_info = self._build_layout(styles, inherit_from=parent_layout)
-                self.line = []
-
-                self._translate_tag(p, layout_info)
-                caption_layout = self._get_layout_class()(
-                    alignment=self.first_alignment, inherit_from=layout_info
-                )
-                for node in self.line:
-                    node.layout_info = Layout(
-                        alignment=self.first_alignment, inherit_from=node.layout_info
-                    )
-                self.first_alignment = None
-
-                caption = Caption(start, end, self.line, styles, caption_layout)
-                captions.append(caption)
-
-        if captions and captions[-1].end == 0:
-            # Arbitrarily make this last 4 seconds. Not ideal...
-            captions[-1].end = (milliseconds + 4000) * 1000
-
-        return captions
-
-    def _get_style_name_from_tag(self, tag):
-        if tag == "i":
-            return "italics"
-        elif tag == "b":
-            return "bold"
-        elif tag == "u":
-            return "underline"
-
-    def _translate_tag(self, tag, inherit_from=None):
-        """
-        :param inherit_from: A Layout object extracted from an ancestor tag
-                to be attached to leaf nodes
-        """
-        # convert text
-        if isinstance(tag, NavigableString):
-            # BeautifulSoup apparently handles unescaping character codes
-            # (e.g. &amp;) automatically. The following variable, therefore,
-            # should contain a plain unicode string.
-            # strips indentation whitespace only
-            pattern = re.compile("^(?:[\n\r]+\\s*)?(.+)")
-            result = pattern.search(tag)
-            if not result:
-                return
-            tag_text = result.groups()[0]
-            self.line.append(CaptionNode.create_text(tag_text, inherit_from))
-        # convert line breaks
-        elif tag.name == "br":
-            self.line.append(CaptionNode.create_break(inherit_from))
-        # convert italics, bold, and underline
-        elif tag.name == "i" or tag.name == "b" or tag.name == "u":
-            style_name = self._get_style_name_from_tag(tag.name)
-            self.line.append(CaptionNode.create_style(True, {style_name: True}))
-            # recursively call function for any children elements
-            for a in tag.contents:
-                self._translate_tag(a, inherit_from)
-            self.line.append(CaptionNode.create_style(False, {style_name: True}))
-        elif tag.name == "span":
-            self._translate_span(tag, inherit_from)
-        else:
-            # recursively call function for any children elements
-            for a in tag.contents:
-                self._translate_tag(a, inherit_from)
-
-    def _translate_span(self, tag, inherit_from=None):
-        # convert tag attributes
-        args = self._translate_attrs(tag)
-        # only include span tag if attributes returned
-        if args:
-            layout_info = self._build_layout(args, inherit_from)
-            # OLD: Create legacy style node
-            # NEW: But pass new layout object
-            node = CaptionNode.create_style(True, args, layout_info)
-            self.line.append(node)
-            # recursively call function for any children elements
-            for a in tag.contents:
-                # NEW: Pass the layout along so that it's eventually attached
-                # to leaf nodes (e.g. text or break)
-                self._translate_tag(a, layout_info)
-            node = CaptionNode.create_style(False, args, layout_info)
-            self.line.append(node)
-        else:
-            for a in tag.contents:
-                self._translate_tag(a, inherit_from)
-
-    def _translate_attrs(self, tag):
-        attrs = {}
-        css_attrs = tag.attrs
-
-        if "class" in css_attrs:
-            attrs["class"] = css_attrs["class"][0].lower()
-        if "id" in css_attrs:
-            attrs["class"] = css_attrs["id"].lower()
-        if "style" in css_attrs:
-            styles = css_attrs["style"].split(";")
-            attrs.update(self._translate_style(attrs, styles))
-
-        return attrs
-
-    # convert attributes from inline CSS
-    def _translate_style(self, attrs, styles):
-        for style in styles:
-            style = style.split(":")
-            if len(style) == 2:
-                css_property, value = style
-            else:
-                continue
-            if css_property == "text-align":
-                self._save_first_alignment(value.strip())
-            else:
-                self._translate_css_property(attrs, css_property, value)
-
-        return attrs
-
-    def _translate_parsed_style(self, styles):
-        # Keep unknown styles by default
-        attrs = styles
-        for css_property in list(styles.keys()):
-            value = styles[css_property]
-            self._translate_css_property(attrs, css_property, value)
-
-        return attrs
-
-    def _translate_css_property(self, attrs, css_property, value):
-        if css_property == "font-family":
-            attrs["font-family"] = value.strip()
-        elif css_property == "font-size":
-            attrs["font-size"] = value.strip()
-        elif css_property == "font-style" and value.strip() == "italic":
-            attrs["italics"] = True
-        elif css_property == "text-decoration" and value.strip() == "underline":
-            attrs["underline"] = True
-        elif css_property == "font-weight" and value.strip() == "bold":
-            attrs["bold"] = True
-        elif css_property == "lang":
-            attrs["lang"] = value.strip()
-        elif css_property == "color":
-            attrs["color"] = value.strip()
-
-    def _save_first_alignment(self, align):
-        """
-        Unlike the other inline CSS attributes parsed in _translate_styles, the
-        'text-align' setting must be applied to a Layout and not to a style
-        because it affects positioning. This Layout must be assigned to the
-        Caption object, and not a Node, because it doesn't make sense to have
-        spans in the same caption with different alignments. Even though the
-        SAMI format seems to in principle accept it, pycaption normalizes to
-        something it can make sense of internally and convert to other formats.
-
-        If there are multiple elements (span, div, etc) in the same line with
-        different alignments, only the first alignment is taken into account.
-
-        If the root element of the caption (sync's first child) has an inline
-        text-align, it is preserved and any children alignment is ignored.
-
-        :param align: A unicode string representing a CSS text-align value
-        """
-        if not self.first_alignment:
-            self.first_alignment = Alignment.from_horizontal_and_vertical_align(
-                text_align=align
-            )
-
-
-class SAMIWriter(BaseWriter):
-    def __init__(self, *args, **kwargs):
-        super().__init__(*args, **kwargs)
-        self.open_span = False
-        self.last_time = None
-
-    def write(self, caption_set):
-        caption_set = deepcopy(caption_set)
-        sami = BeautifulSoup(SAMI_BASE_MARKUP, "lxml-xml")
-
-        caption_set.layout_info = self._relativize_and_fit_to_screen(
-            caption_set.layout_info
-        )
-
-        primary = None
-
-        for lang in caption_set.get_languages():
-            self.last_time = None
-            if primary is None:
-                primary = lang
-
-            caption_set.set_layout_info(
-                lang,
-                self._relativize_and_fit_to_screen(caption_set.get_layout_info(lang)),
-            )
-
-            for caption in caption_set.get_captions(lang):
-                # Loop through all captions/nodes and apply transformations to
-                # layout in function of the provided or default settings
-                caption.layout_info = self._relativize_and_fit_to_screen(
-                    caption.layout_info
-                )
-                for node in caption.nodes:
-                    node.layout_info = self._relativize_and_fit_to_screen(
-                        node.layout_info
-                    )
-                sami = self._recreate_p_tag(caption, sami, lang, primary, caption_set)
-
-        stylesheet = self._recreate_stylesheet(caption_set)
-        sami.find("style").append(stylesheet)
-
-        a = sami.prettify(formatter=None).split("\n")
-        caption_content = "\n".join(a[1:])
-        return caption_content
-
-    def _recreate_p_tag(self, caption, sami, lang, primary, captions):
-        """
-        Creates a p tag for the given caption, attach it to the sami object
-        and return it.
-
-        :type caption: Caption
-        :type sami: BeautifulSoup
-        :type lang: str
-        :type primary: str
-        :type captions: CaptionSet
-
-        :rtype: BeautifulSoup
-        """
-        time = caption.start // 1000
-
-        if self.last_time and time != self.last_time:
-            sami = self._recreate_blank_tag(sami, caption, lang, primary, captions)
-
-        self.last_time = caption.end // 1000
-
-        sami, sync = self._recreate_sync(sami, lang, primary, time)
-
-        p = sami.new_tag("p")
-
-        p_style = ""
-        for attr, value in list(self._recreate_style(caption.style).items()):
-            p_style += f"{attr}:{value};"
-        if p_style:
-            p["p_style"] = p_style
-
-        p["class"] = self._recreate_p_lang(caption, lang, captions)
-        p.string = self._recreate_text(caption.nodes)
-
-        sync.append(p)
-
-        return sami
-
-    def _recreate_sync(self, sami, lang, primary, time):
-        """
-        Creates a sync tag for a given language and timing (if it doesn't
-        already exist), attach it to the sami body and return the sami
-        BeautifulSoup object.
-
-        :type sami: BeautifulSoup
-        :type lang: str
-        :type primary: str
-        :type time: int
-
-        :rtype: BeautifulSoup
-        """
-        if lang == primary:
-            sync = sami.new_tag("sync", start=time)
-            sami.body.append(sync)
-        else:
-            sync = sami.find("sync", start=time)
-            if sync is None:
-                sami, sync = self._find_closest_sync(sami, time)
-
-        return sami, sync
-
-    def _find_closest_sync(self, sami, time):
-        sync = sami.new_tag("sync", start=time)
-
-        earlier = sami.find_all("sync", start=lambda x: int(x) < time)
-        if earlier:
-            last_sync = earlier[-1]
-            last_sync.insert_after(sync)
-        else:
-            later = sami.find_all("sync", start=lambda x: int(x) > time)
-            if later:
-                last_sync = later[0]
-                last_sync.insert_before(sync)
-        return sami, sync
-
-    def _recreate_blank_tag(self, sami, caption, lang, primary, captions):
-        sami, sync = self._recreate_sync(sami, lang, primary, self.last_time)
-
-        p = sami.new_tag("p")
-        p["class"] = self._recreate_p_lang(caption, lang, captions)
-        p.string = "&nbsp;"
-
-        sync.append(p)
-
-        return sami
-
-    def _recreate_p_lang(self, caption, lang, captions):
-        try:
-            if "lang" in captions.get_style(caption.style["class"]):
-                return caption.style["class"]
-        except KeyError:
-            pass
-        return lang
-
-    def _recreate_stylesheet(self, caption_set):
-        stylesheet = "<!--"
-
-        for attr, value in caption_set.get_styles():
-            if value != {} and not attr.startswith("::"):
-                stylesheet += self._recreate_style_block(
-                    attr, value, caption_set.layout_info
-                )
-
-        for lang in caption_set.get_languages():
-            lang_string = f"lang: {lang}"
-            if lang_string not in stylesheet:
-                stylesheet += self._recreate_style_block(
-                    lang, {"lang": lang}, caption_set.get_layout_info(lang)
-                )
-
-        return stylesheet + "   -->"
-
-    def _recreate_style_block(self, target, rules, layout_info):
-        """
-        :param target: A unicode string representing the target of the styling
-            rules.
-        :param rules: A dictionary with CSS-like styling rules.
-
-        :param layout_info: A Layout object providing positioning information
-            to be converted to CSS
-        """
-        if target not in ["p", "sync", "span"]:
-            # If it's not a valid SAMI element, then it's a custom class name
-            selector = f".{target}"
-        else:
-            selector = target
-
-        sami_style = f"\n    {selector} {{\n    "
-
-        if layout_info and layout_info.padding:
-            rules.update(
-                {
-                    "margin-top": str(layout_info.padding.before),
-                    "margin-right": str(layout_info.padding.end),
-                    "margin-bottom": str(layout_info.padding.after),
-                    "margin-left": str(layout_info.padding.start),
-                }
-            )
-
-        for attr, value in sorted(self._recreate_style(rules).items()):
-            sami_style += f" {attr}: {value};\n    "
-
-        return sami_style + "}\n"
-
-    def _recreate_text(self, caption):
-        line = ""
-
-        for node in caption:
-            if node.type_ == CaptionNode.TEXT:
-                line += self._encode(node.content) + " "
-            elif node.type_ == CaptionNode.BREAK:
-                line = line.rstrip() + "<br/>\n    "
-            elif node.type_ == CaptionNode.STYLE:
-                line = self._recreate_line_style(line, node)
-
-        return line.rstrip()
-
-    def _recreate_line_style(self, line, node):
-        if node.start:
-            if self.open_span:
-                line = line.rstrip() + "</span> "
-            line = self._recreate_span(line, node.content)
-        else:
-            if self.open_span:
-                line = line.rstrip() + "</span> "
-                self.open_span = False
-
-        return line
-
-    def _recreate_span(self, line, content):
-        style = ""
-        klass = ""
-        if "class" in content:
-            klass += f' class="{content["class"]}"'
-
-        for attr, value in list(self._recreate_style(content).items()):
-            style += f"{attr}:{value};"
-
-        if style or klass:
-            if style:
-                style = f' style="{style}"'
-            line += f"<span{klass}{style}>"
-            self.open_span = True
-
-        return line
-
-    def _recreate_style(self, rules):
-        """
-        :param rules: A dictionary with CSS-like styling rules
-        """
-        sami_style = {}
-
-        for key, value in list(rules.items()):
-            # Recreate original CSS rules from internal style
-            if key == "italics" and value is True:
-                sami_style["font-style"] = "italic"
-            elif key == "bold" and value is True:
-                sami_style["font-weight"] = "bold"
-            elif key == "underline" and value is True:
-                sami_style["text-decoration"] = "underline"
-            else:
-                sami_style[key] = value
-
-        return sami_style
-
-    def _encode(self, s):
-        """
-        Encodes plain unicode string to proper SAMI file escaping special
-        characters in case they appear in the string.
-        :type s: str
-        """
-        return escape(s)
-
-
-class SAMIParser(HTMLParser):
-    def __init__(self, *args, **kw):
-        HTMLParser.__init__(self, *args, **kw)
-        self.sami = ""
-        self.line = ""
-        self.styles = {}
-        self.queue = deque()
-        self.langs = set()
-        self.last_element = ""
-        self.name2codepoint = name2codepoint.copy()
-        self.name2codepoint["apos"] = 0x0027
-        self.convert_charrefs = False
-
-    def handle_starttag(self, tag, attrs):
-        """
-        Override the parser's handling of starttags
-        :param tag: unicode string indicating the tag type (e.g. "head" or "p")
-        :param tag: list of attribute tuples of type ('name', 'value')
-        """
-        self.last_element = tag
-
-        # treat divs as spans
-        if tag == "div":
-            tag = "span"
-
-        # figure out the caption language of P tags
-        if tag == "p":
-            lang = self._find_lang(attrs)
-
-            # if no language detected, set it as the default
-            lang = lang or DEFAULT_LANGUAGE_CODE
-            attrs.append(("lang", lang))
-            self.langs.add(lang)
-
-        # clean-up line breaks
-        if tag == "br":
-            self.sami += "<br/>"
-        # add tag to queue
-        else:
-            # if already in queue, first close tags off in LIFO order
-            while tag in self.queue:
-                closer = self.queue.pop()
-                self.sami += f"</{closer}>"
-            # open new tag in queue
-            self.queue.append(tag)
-            # add tag with attributes
-            for attr, value in attrs:
-                tag += f' {attr.lower()}="{value}"'
-            self.sami += f"<{tag}>"
-
-    # override the parser's handling of endtags
-    def handle_endtag(self, tag):
-        # treat divs as spans
-        if tag == "div":
-            tag = "span"
-
-        # handle incorrectly formatted sync/p tags
-        if tag in ["p", "sync"] and tag == self.last_element:
-            return
-
-        # close off tags in LIFO order, if matching starting tag in queue
-        while tag in self.queue:
-            closing_tag = self.queue.pop()
-            self.sami += f"</{closing_tag}>"
-
-    def handle_entityref(self, name):
-        if name in ["gt", "lt"]:
-            self.sami += f"&{name};"
-        else:
-            try:
-                self.sami += chr(self.name2codepoint[name])
-            except (KeyError, ValueError):
-                self.sami += f"&{name}"
-
-        self.last_element = ""
-
-    def handle_charref(self, name):
-        if name[0] == "x":
-            self.sami += chr(int(name[1:], 16))
-        else:
-            self.sami += chr(int(name))
-
-    # override the parser's handling of data
-    def handle_data(self, data):
-        self.sami += data
-        self.last_element = ""
-
-    # override the parser's feed function
-    def feed(self, data):
-        """
-        :param data: Raw SAMI unicode string
-        :returns: tuple (str, dict, set)
-        """
-        no_cc = "no closed captioning available"
-
-        if "<html" in data.lower():
-            raise CaptionReadSyntaxError("SAMI File seems to be an HTML file.")
-        elif no_cc in data.lower():
-            raise CaptionReadSyntaxError(f'SAMI File contains "{no_cc}"')
-
-        # try to find style tag in SAMI
-        # prevent BS4 error with huge SAMI files with unclosed tags
-        index = data.lower().find("</head>")
-        style = BeautifulSoup(data[:index], "lxml").find("style")
-        if style and style.contents:
-            self.styles = self._css_parse(" ".join(style.contents))
-        else:
-            self.styles = {}
-
-        # fix erroneous italics tags
-        data = data.replace("<i/>", "<i>")
-
-        # fix awkward tags found in some SAMIs
-        data = data.replace(";>", ">")
-        HTMLParser.feed(self, data)
-
-        # close any tags that remain in the queue
-        while self.queue != deque([]):
-            closing_tag = self.queue.pop()
-            self.sami += f"</{closing_tag}>"
-
-        return self.sami, self.styles, self.langs
-
-    # parse the SAMI's stylesheet
-    def _css_parse(self, css):
-        """
-        Parse styling via cssutils modules
-        :rtype: dict
-        """
-        sheet = parseString(css)
-        style_sheet = {}
-
-        for rule in sheet:
-            new_style = {}
-            selector = rule.selectorText.lower()
-            if selector[0] in ["#", "."]:
-                selector = selector[1:]
-            # keep any style attributes that are needed
-            for prop in rule.style:
-                if prop.name == "color":
-                    try:
-                        cv = cssutils_css.ColorValue(prop.value)
-                    except SyntaxErr:
-                        raise CaptionReadSyntaxError(
-                            f"Invalid color value: {prop.value}. Check for "
-                            f"missing # before hex values or misspelled color "
-                            f"values."
-                        )
-                    # Code for RGB to hex conversion comes from
-                    # http://bit.ly/1kwfBnQ
-                    new_style["color"] = f"#{cv.red:02x}{cv.green:02x}" f"{cv.blue:02x}"
-                else:
-                    new_style[prop.name] = prop.value
-            if new_style:
-                style_sheet[selector] = new_style
-
-        return style_sheet
-
-    def _find_lang(self, attrs):
-        for attr, value in attrs:
-            # if lang is an attribute of the tag
-            if attr.lower() == "lang":
-                return value[:2]
-            # if the P tag has a class, try and find the language
-            if attr.lower() == "class":
-                try:
-                    return self.styles[value.lower()]["lang"]
-                except KeyError:
-                    pass
-
-        return None
diff --git a/pycaption/sami/__init__.py b/pycaption/sami/__init__.py
new file mode 100644
index 00000000..5a09eefb
--- /dev/null
+++ b/pycaption/sami/__init__.py
@@ -0,0 +1,4 @@
+from .constants import SAMI_BASE_MARKUP  # noqa: F401
+from .parser import SAMIParser  # noqa: F401
+from .reader import SAMIReader  # noqa: F401
+from .writer import SAMIWriter  # noqa: F401
diff --git a/pycaption/sami/constants.py b/pycaption/sami/constants.py
new file mode 100644
index 00000000..38aecab0
--- /dev/null
+++ b/pycaption/sami/constants.py
@@ -0,0 +1,23 @@
+from logging import FATAL
+
+from cssutils import log
+
+from ..geometry import HorizontalAlignmentEnum
+
+log.setLevel(FATAL)
+
+SAMI_BASE_MARKUP = """
+<sami>
+    <head>
+        <style type="text/css"/>
+    </head>
+    <body/>
+</sami>"""
+
+HORIZONTAL_ALIGNMENT_MAP = {
+    HorizontalAlignmentEnum.LEFT: "left",
+    HorizontalAlignmentEnum.CENTER: "center",
+    HorizontalAlignmentEnum.RIGHT: "right",
+    HorizontalAlignmentEnum.START: "left",
+    HorizontalAlignmentEnum.END: "right",
+}
diff --git a/pycaption/sami/parser.py b/pycaption/sami/parser.py
new file mode 100644
index 00000000..eebcb3f9
--- /dev/null
+++ b/pycaption/sami/parser.py
@@ -0,0 +1,179 @@
+from collections import deque
+from html.entities import name2codepoint
+from html.parser import HTMLParser
+from xml.dom import SyntaxErr
+
+from bs4 import BeautifulSoup
+from cssutils import css as cssutils_css
+from cssutils import parseString
+
+from ..base import DEFAULT_LANGUAGE_CODE
+from ..exceptions import CaptionReadSyntaxError
+
+
+class SAMIParser(HTMLParser):
+    """HTML parser that normalizes raw SAMI markup into well-formed XML.
+
+    Extracts CSS stylesheet rules and discovers caption languages during
+    a single pass.  The result is a tuple of (normalized_xml, styles, langs)
+    consumed by SAMIReader.
+    """
+
+    def __init__(self, *args, **kw):
+        HTMLParser.__init__(self, *args, **kw)
+        self.sami = ""
+        self.styles = {}
+        self.queue = deque()
+        self.langs = set()
+        self.last_element = ""
+        self.name2codepoint = name2codepoint.copy()
+        self.name2codepoint["apos"] = 0x0027
+        self.convert_charrefs = False
+
+    def handle_starttag(self, tag, attrs):
+        """Normalize opening tags: treat <div> as <span>, detect language on <p>."""
+        self.last_element = tag
+
+        if tag == "div":
+            tag = "span"
+
+        if tag == "p":
+            lang = self._find_lang(attrs)
+            lang = lang or DEFAULT_LANGUAGE_CODE
+            attrs.append(("lang", lang))
+            self.langs.add(lang)
+
+        if tag == "br":
+            self.sami += "<br/>"
+        else:
+            # Close any already-open instance of this tag (LIFO) before re-opening
+            while tag in self.queue:
+                closer = self.queue.pop()
+                self.sami += f"</{closer}>"
+            self.queue.append(tag)
+            for attr, value in attrs:
+                tag += f' {attr.lower()}="{value}"'
+            self.sami += f"<{tag}>"
+
+    def handle_endtag(self, tag):
+        """Close tags in LIFO order; handle SAMI's malformed sync/p nesting."""
+        if tag == "div":
+            tag = "span"
+
+        # Skip duplicate close when the tag was just opened with no content
+        if tag in ["p", "sync"] and tag == self.last_element:
+            return
+
+        while tag in self.queue:
+            closing_tag = self.queue.pop()
+            self.sami += f"</{closing_tag}>"
+
+    def handle_entityref(self, name):
+        """Convert named HTML entities to characters; preserve &gt; and &lt;."""
+        if name in ["gt", "lt"]:
+            self.sami += f"&{name};"
+        else:
+            try:
+                self.sami += chr(self.name2codepoint[name])
+            except (KeyError, ValueError):
+                self.sami += f"&{name}"
+
+        self.last_element = ""
+
+    def handle_charref(self, name):
+        """Convert numeric character references (&#NNN; or &#xHHH;) to characters."""
+        self.sami += chr(int(name[1:], 16) if name[0] == "x" else int(name))
+
+    def handle_data(self, data):
+        """Append raw text content to the output."""
+        self.sami += data
+        self.last_element = ""
+
+    def feed(self, data):
+        """Parse raw SAMI content and return normalized XML, styles, and languages.
+
+        :param data: Raw SAMI unicode string
+        :returns: (normalized_xml, styles_dict, languages_set)
+        :rtype: tuple[str, dict, set]
+        :raises CaptionReadSyntaxError: if the file is HTML or has no captions
+        """
+        no_cc = "no closed captioning available"
+
+        if "<html" in data.lower():
+            raise CaptionReadSyntaxError("SAMI File seems to be an HTML file.")
+        elif no_cc in data.lower():
+            raise CaptionReadSyntaxError(f'SAMI File contains "{no_cc}"')
+
+        index = data.lower().find("</head>")
+        style = BeautifulSoup(data[:index], "lxml").find("style")
+        if style and style.contents:
+            self.styles = self._css_parse(" ".join(style.contents))
+        else:
+            self.styles = {}
+
+        # Fix common SAMI authoring errors
+        data = data.replace("<i/>", "<i>")
+        data = data.replace(";>", ">")
+        HTMLParser.feed(self, data)
+
+        # Close any tags left open at end of document
+        while self.queue:
+            closing_tag = self.queue.pop()
+            self.sami += f"</{closing_tag}>"
+
+        return self.sami, self.styles, self.langs
+
+    @staticmethod
+    def _css_parse(css):
+        """Parse a SAMI STYLE block into a dict of selector → properties.
+
+        Color values are normalized to 6-digit hex (#rrggbb).
+
+        :type css: str
+        :rtype: dict[str, dict[str, str]]
+        """
+        sheet = parseString(css)
+        style_sheet = {}
+
+        for rule in sheet:
+            new_style = {}
+            selector = rule.selectorText.lower()
+            if selector[0] in ["#", "."]:
+                selector = selector[1:]
+            for prop in rule.style:
+                if prop.name == "color":
+                    try:
+                        cv = cssutils_css.ColorValue(prop.value)
+                    except SyntaxErr:
+                        raise CaptionReadSyntaxError(
+                            f"Invalid color value: {prop.value}. Check for "
+                            f"missing # before hex values or misspelled color "
+                            f"values."
+                        )
+                    new_style["color"] = f"#{cv.red:02x}{cv.green:02x}{cv.blue:02x}"
+                else:
+                    new_style[prop.name] = prop.value
+            if new_style:
+                style_sheet[selector] = new_style
+
+        return style_sheet
+
+    def _find_lang(self, attrs):
+        """Detect caption language from a <p> tag's attributes.
+
+        Checks for an explicit lang attribute first, then looks up the
+        class name in the parsed stylesheet for a lang property.
+
+        :param attrs: list of (name, value) attribute tuples
+        :rtype: str | None
+        """
+        for attr, value in attrs:
+            if attr.lower() == "lang":
+                return value[:2]
+            if attr.lower() == "class":
+                try:
+                    return self.styles[value.lower()]["lang"]
+                except KeyError:
+                    pass
+
+        return None
diff --git a/pycaption/sami/reader.py b/pycaption/sami/reader.py
new file mode 100644
index 00000000..77f9d698
--- /dev/null
+++ b/pycaption/sami/reader.py
@@ -0,0 +1,314 @@
+from bs4 import BeautifulSoup, NavigableString
+
+from ..base import BaseReader, Caption, CaptionList, CaptionNode, CaptionSet
+from ..exceptions import (
+    CaptionReadNoCaptions,
+    CaptionReadTimingError,
+    InvalidInputError,
+)
+from ..geometry import Alignment, Layout, Padding, Size
+from .parser import SAMIParser
+
+_TAG_TO_STYLE = {"i": "italics", "b": "bold", "u": "underline"}
+
+
+class SAMIReader(BaseReader):
+    """Reads SAMI caption files into a CaptionSet.
+
+    Supports CSS-based styling (font, color, text-decoration), margin-based
+    positioning converted to Layout objects, and multi-language documents.
+    """
+
+    def __init__(self, *args, **kw):
+        super().__init__(*args, **kw)
+        self.line = []
+        self.first_alignment = None
+
+    def detect(self, content):
+        """Return True if content looks like a SAMI document."""
+        return "<sami" in content.lower()
+
+    def read(self, content):
+        """Parse a SAMI string into a CaptionSet.
+
+        :type content: str
+        :rtype: CaptionSet
+        :raises InvalidInputError: if content is not a string
+        :raises CaptionReadNoCaptions: if no captions are found
+        """
+        if not isinstance(content, str):
+            raise InvalidInputError("The content is not a unicode string.")
+
+        content, doc_styles, doc_langs = SAMIParser().feed(content)
+        sami_soup = BeautifulSoup(content, features="lxml")
+
+        global_layout = self._build_layout(doc_styles.get("p", {}))
+
+        caption_dict = {}
+        for language in doc_langs:
+            lang_layout = None
+            for target, styling in list(doc_styles.items()):
+                if target not in ["p", "sync", "span"]:
+                    if styling.get("lang", None) == language:
+                        lang_layout = self._build_layout(
+                            doc_styles.get(target, {}), inherit_from=global_layout
+                        )
+                        break
+            lang_layout = lang_layout or global_layout
+            lang_captions = self._translate_lang(language, sami_soup, lang_layout)
+
+            caption_dict[language] = lang_captions
+
+        caption_set = CaptionSet(caption_dict, layout_info=global_layout)
+
+        for style in list(doc_styles.items()):
+            style = (style[0], self._translate_parsed_style(style[1]))
+
+        caption_set.set_styles(doc_styles)
+
+        if caption_set.is_empty():
+            raise CaptionReadNoCaptions("empty caption file")
+
+        return caption_set
+
+    def _build_layout(self, styles, inherit_from=None):
+        """Build a Layout from CSS margin and text-align properties.
+
+        :type styles: dict
+        :param inherit_from: parent Layout whose values are used as defaults
+        :rtype: Layout
+        """
+        alignment = Alignment.from_horizontal_and_vertical_align(
+            text_align=styles.get("text-align")
+        )
+        return Layout(
+            origin=None,
+            extent=None,
+            padding=self._get_padding(styles),
+            alignment=alignment,
+            inherit_from=inherit_from,
+        )
+
+    def _get_padding(self, styles):
+        """Convert CSS margin-* properties to a Padding object.
+
+        :rtype: Padding | None
+        """
+        margin_before = self._get_size(styles, "margin-top")
+        margin_after = self._get_size(styles, "margin-bottom")
+        margin_start = self._get_size(styles, "margin-left")
+        margin_end = self._get_size(styles, "margin-right")
+        if not any([margin_before, margin_after, margin_start, margin_end]):
+            return None
+        return Padding(
+            before=margin_before,
+            after=margin_after,
+            start=margin_start,
+            end=margin_end,
+        )
+
+    def _get_size(self, styles, style_label):
+        """Extract a Size from a CSS property value string.
+
+        :rtype: Size | None
+        """
+        value_from_style = styles.get(style_label, None)
+        if not value_from_style:
+            return None
+        return Size.from_string(value_from_style)
+
+    def _translate_lang(self, language, sami_soup, parent_layout):
+        """Convert all <p> tags for a language into a CaptionList.
+
+        Sets end times by using the next caption's start time.  The last
+        caption gets an arbitrary 4-second duration if no end is available.
+
+        :rtype: CaptionList
+        """
+        captions = CaptionList(layout_info=parent_layout)
+        milliseconds = 0
+
+        for p in sami_soup.select(f"p[lang|={language}]"):
+            start_str = p.parent.get("start")
+            if not start_str:
+                raise CaptionReadTimingError(
+                    f"Missing start time on the following line: {p.parent}."
+                )
+            milliseconds = int(float(start_str))
+            start = milliseconds * 1000
+
+            self._backfill_end_times(captions, start)
+
+            if p.get_text().strip():
+                caption = self._build_caption(p, start, parent_layout)
+                captions.append(caption)
+
+        if captions and captions[-1].end == 0:
+            captions[-1].end = (milliseconds + 4000) * 1000
+
+        return captions
+
+    @staticmethod
+    def _backfill_end_times(captions, start):
+        """Set end time on preceding captions that don't have one yet."""
+        for i in reversed(range(len(captions))):
+            if captions[i].end != 0:
+                break
+            if captions[i].start != start:
+                captions[i].end = start
+
+    def _build_caption(self, p, start, parent_layout):
+        """Parse a single <p> element into a Caption object.
+
+        :rtype: Caption
+        """
+        self.first_alignment = None
+        styles = self._translate_attrs(p)
+        layout_info = self._build_layout(styles, inherit_from=parent_layout)
+        self.line = []
+
+        self._translate_tag(p, layout_info)
+        caption_layout = Layout(
+            alignment=self.first_alignment, inherit_from=layout_info
+        )
+        for node in self.line:
+            node.layout_info = Layout(
+                alignment=self.first_alignment, inherit_from=node.layout_info
+            )
+        self.first_alignment = None
+
+        return Caption(start, 0, self.line, styles, caption_layout)
+
+    def _translate_tag(self, tag, inherit_from=None):
+        """Recursively convert a BeautifulSoup element into CaptionNodes.
+
+        Handles NavigableString (text), <br> (break), <i>/<b>/<u> (style),
+        and <span> (class/inline-style).
+        """
+        if isinstance(tag, NavigableString):
+            tag_text = str(tag)
+            if tag_text and tag_text[0] in "\n\r":
+                tag_text = tag_text.lstrip()
+            tag_text = tag_text.rstrip("\n\r")
+            if not tag_text:
+                return
+            self.line.append(CaptionNode.create_text(tag_text, inherit_from))
+        elif tag.name == "br":
+            self.line.append(CaptionNode.create_break(inherit_from))
+        elif tag.name == "i" or tag.name == "b" or tag.name == "u":
+            style_name = _TAG_TO_STYLE.get(tag.name)
+            self.line.append(CaptionNode.create_style(True, {style_name: True}))
+            for a in tag.contents:
+                self._translate_tag(a, inherit_from)
+            self.line.append(CaptionNode.create_style(False, {style_name: True}))
+        elif tag.name == "span":
+            self._translate_span(tag, inherit_from)
+        else:
+            for a in tag.contents:
+                self._translate_tag(a, inherit_from)
+
+    def _translate_span(self, tag, inherit_from=None):
+        """Convert a <span> tag into style-start/end nodes with layout.
+
+        If the span has styling attributes, wraps children between style
+        nodes.  Otherwise processes children without wrapping.
+        """
+        args = self._translate_attrs(tag)
+        if args:
+            layout_info = self._build_layout(args, inherit_from)
+            node = CaptionNode.create_style(True, args, layout_info)
+            self.line.append(node)
+            for a in tag.contents:
+                self._translate_tag(a, layout_info)
+            node = CaptionNode.create_style(False, args, layout_info)
+            self.line.append(node)
+        else:
+            for a in tag.contents:
+                self._translate_tag(a, inherit_from)
+
+    def _translate_attrs(self, tag):
+        """Extract class, id, and inline style from a tag into a style dict.
+
+        :rtype: dict
+        """
+        attrs = {}
+        css_attrs = tag.attrs
+
+        if "class" in css_attrs:
+            attrs["class"] = css_attrs["class"][0].lower()
+        if "id" in css_attrs:
+            attrs["class"] = css_attrs["id"].lower()
+        if "style" in css_attrs:
+            styles = css_attrs["style"].split(";")
+            attrs.update(self._translate_style(attrs, styles))
+
+        return attrs
+
+    def _translate_style(self, attrs, styles):
+        """Parse inline CSS declarations into the style dict.
+
+        text-align is captured separately as a Layout alignment; other
+        properties are delegated to _translate_css_property.
+
+        :rtype: dict
+        """
+        for style in styles:
+            style = style.split(":")
+            if len(style) == 2:
+                css_property, value = style
+            else:
+                continue
+            if css_property == "text-align":
+                self._save_first_alignment(value.strip())
+            else:
+                self._translate_css_property(attrs, css_property, value)
+
+        return attrs
+
+    def _translate_parsed_style(self, styles):
+        """Normalize a stylesheet rule dict by mapping CSS names to internal keys.
+
+        Mutates the dict in-place (e.g. font-style:italic → italics:True).
+
+        :rtype: dict
+        """
+        attrs = styles
+        for css_property in list(styles.keys()):
+            value = styles[css_property]
+            self._translate_css_property(attrs, css_property, value)
+
+        return attrs
+
+    @staticmethod
+    def _translate_css_property(attrs, css_property, value):
+        """Map a single CSS property to pycaption's internal style key.
+
+        Recognized properties: font-family, font-size, font-style (italic),
+        text-decoration (underline), font-weight (bold), lang, color.
+        """
+        if css_property == "font-family":
+            attrs["font-family"] = value.strip()
+        elif css_property == "font-size":
+            attrs["font-size"] = value.strip()
+        elif css_property == "font-style" and value.strip() == "italic":
+            attrs["italics"] = True
+        elif css_property == "text-decoration" and value.strip() == "underline":
+            attrs["underline"] = True
+        elif css_property == "font-weight" and value.strip() == "bold":
+            attrs["bold"] = True
+        elif css_property == "lang":
+            attrs["lang"] = value.strip()
+        elif css_property == "color":
+            attrs["color"] = value.strip()
+
+    def _save_first_alignment(self, align):
+        """Capture the first text-align value encountered in a caption.
+
+        Only the first alignment wins — subsequent spans with different
+        alignments are ignored, since SAMI normalizes to one alignment
+        per caption.
+        """
+        if not self.first_alignment:
+            self.first_alignment = Alignment.from_horizontal_and_vertical_align(
+                text_align=align
+            )
diff --git a/pycaption/sami/writer.py b/pycaption/sami/writer.py
new file mode 100644
index 00000000..46f32486
--- /dev/null
+++ b/pycaption/sami/writer.py
@@ -0,0 +1,267 @@
+from copy import deepcopy
+from xml.sax.saxutils import escape
+
+from bs4 import BeautifulSoup
+
+from ..base import BaseWriter, CaptionNode
+from .constants import HORIZONTAL_ALIGNMENT_MAP, SAMI_BASE_MARKUP
+
+_NON_CSS_KEYS = frozenset(
+    {
+        "classes",
+        "class",
+        "ruby",
+        "ruby_text",
+        "timestamp",
+        "name",
+        "sami_type",
+        "lang",
+        "webvtt_positioning",
+        "writing_direction",
+    }
+)
+
+
+class SAMIWriter(BaseWriter):
+    """Writes a CaptionSet to SAMI markup."""
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.open_span = False
+        self.last_time = None
+
+    def write(self, caption_set):
+        """Serialize a CaptionSet into a SAMI document string."""
+        caption_set = deepcopy(caption_set)
+        sami = BeautifulSoup(SAMI_BASE_MARKUP, "lxml-xml")
+
+        caption_set.layout_info = self._relativize_and_fit_to_screen(
+            caption_set.layout_info
+        )
+
+        primary = None
+
+        for lang in caption_set.get_languages():
+            self.last_time = None
+            if primary is None:
+                primary = lang
+
+            caption_set.set_layout_info(
+                lang,
+                self._relativize_and_fit_to_screen(caption_set.get_layout_info(lang)),
+            )
+
+            for caption in caption_set.get_captions(lang):
+                caption.layout_info = self._relativize_and_fit_to_screen(
+                    caption.layout_info
+                )
+                for node in caption.nodes:
+                    node.layout_info = self._relativize_and_fit_to_screen(
+                        node.layout_info
+                    )
+                sami = self._recreate_p_tag(caption, sami, lang, primary, caption_set)
+
+        stylesheet = self._recreate_stylesheet(caption_set)
+        sami.find("style").append(stylesheet)
+
+        a = sami.prettify(formatter=None).split("\n")
+        caption_content = "\n".join(a[1:])
+        return caption_content
+
+    def _recreate_p_tag(self, caption, sami, lang, primary, captions):
+        """Build a <sync><p> block for a single caption with styling and alignment."""
+        time = caption.start // 1000
+
+        if self.last_time and time != self.last_time:
+            sami = self._recreate_blank_tag(sami, caption, lang, primary, captions)
+
+        self.last_time = caption.end // 1000
+
+        sami, sync = self._recreate_sync(sami, lang, primary, time)
+
+        p = sami.new_tag("p")
+
+        p_style = ""
+        for attr, value in self._recreate_style(caption.style).items():
+            p_style += f"{attr}:{value};"
+
+        if caption.layout_info and caption.layout_info.alignment:
+            h = caption.layout_info.alignment.horizontal
+            if h:
+                css_align = HORIZONTAL_ALIGNMENT_MAP.get(h)
+                if css_align:
+                    p_style += f"text-align:{css_align};"
+
+        if p_style:
+            p["p_style"] = p_style
+
+        p["class"] = self._recreate_p_lang(caption, lang, captions)
+        p.string = self._recreate_text(caption.nodes)
+
+        sync.append(p)
+
+        return sami
+
+    def _recreate_sync(self, sami, lang, primary, time):
+        """Find or create a <sync> tag at the given millisecond timestamp."""
+        if lang == primary:
+            sync = sami.new_tag("sync", start=time)
+            sami.body.append(sync)
+        else:
+            sync = sami.find("sync", start=time)
+            if sync is None:
+                sami, sync = self._find_closest_sync(sami, time)
+
+        return sami, sync
+
+    @staticmethod
+    def _find_closest_sync(sami, time):
+        """Insert a new <sync> tag in chronological order among existing syncs."""
+        sync = sami.new_tag("sync", start=time)
+
+        earlier = sami.find_all("sync", start=lambda x: int(x) < time)
+        if earlier:
+            last_sync = earlier[-1]
+            last_sync.insert_after(sync)
+        else:
+            later = sami.find_all("sync", start=lambda x: int(x) > time)
+            if later:
+                last_sync = later[0]
+                last_sync.insert_before(sync)
+        return sami, sync
+
+    def _recreate_blank_tag(self, sami, caption, lang, primary, captions):
+        """Insert an &nbsp; paragraph to clear the previous caption at its end time."""
+        sami, sync = self._recreate_sync(sami, lang, primary, self.last_time)
+
+        p = sami.new_tag("p")
+        p["class"] = self._recreate_p_lang(caption, lang, captions)
+        p.string = "&nbsp;"
+
+        sync.append(p)
+
+        return sami
+
+    @staticmethod
+    def _recreate_p_lang(caption, lang, captions):
+        """Return the CSS class for a <p> tag, preferring the language class."""
+        try:
+            if "lang" in captions.get_style(caption.style["class"]):
+                return caption.style["class"]
+        except KeyError:
+            pass
+        return lang
+
+    def _recreate_stylesheet(self, caption_set):
+        """Generate the CSS stylesheet block placed inside <style>."""
+        stylesheet = "<!--"
+
+        for attr, value in caption_set.get_styles():
+            if value != {} and not attr.startswith("::"):
+                stylesheet += self._recreate_style_block(
+                    attr, value, caption_set.layout_info
+                )
+
+        for lang in caption_set.get_languages():
+            lang_string = f"lang: {lang}"
+            if lang_string not in stylesheet:
+                stylesheet += self._recreate_style_block(
+                    lang, {"lang": lang}, caption_set.get_layout_info(lang)
+                )
+
+        return stylesheet + "   -->"
+
+    def _recreate_style_block(self, target, rules, layout_info):
+        """Format a single CSS rule block (selector + properties) for the stylesheet."""
+        if target not in ["p", "sync", "span"]:
+            selector = f".{target}"
+        else:
+            selector = target
+
+        sami_style = f"\n    {selector} {{\n    "
+
+        rules = dict(rules)
+        if layout_info and layout_info.padding:
+            rules.update(
+                {
+                    "margin-top": str(layout_info.padding.before),
+                    "margin-right": str(layout_info.padding.end),
+                    "margin-bottom": str(layout_info.padding.after),
+                    "margin-left": str(layout_info.padding.start),
+                }
+            )
+
+        css_props = self._recreate_style(rules)
+        if "lang" in rules:
+            css_props["lang"] = rules["lang"]
+
+        for attr, value in sorted(css_props.items()):
+            sami_style += f" {attr}: {value};\n    "
+
+        return sami_style + "}\n"
+
+    def _recreate_text(self, caption):
+        """Serialize caption nodes into an HTML text string with inline markup."""
+        line = ""
+
+        for node in caption:
+            if node.type_ == CaptionNode.TEXT:
+                line += escape(node.content) + " "
+            elif node.type_ == CaptionNode.BREAK:
+                line = line.rstrip() + "<br/>\n    "
+            elif node.type_ == CaptionNode.STYLE:
+                line = self._recreate_line_style(line, node)
+
+        return line.rstrip()
+
+    def _recreate_line_style(self, line, node):
+        """Handle style node transitions, opening and closing <span> tags."""
+        if node.start:
+            if self.open_span:
+                line = line.rstrip() + "</span> "
+            line = self._recreate_span(line, node.content)
+        else:
+            if self.open_span:
+                line = line.rstrip() + "</span> "
+                self.open_span = False
+
+        return line
+
+    def _recreate_span(self, line, content):
+        """Build an opening <span> with class and/or inline style attributes."""
+        style = ""
+        klass = ""
+        if "classes" in content:
+            klass += f' class="{" ".join(content["classes"])}"'
+        elif "class" in content:
+            klass += f' class="{content["class"]}"'
+
+        for attr, value in self._recreate_style(content).items():
+            style += f"{attr}:{value};"
+
+        if style or klass:
+            if style:
+                style = f' style="{style}"'
+            line += f"<span{klass}{style}>"
+            self.open_span = True
+
+        return line
+
+    @staticmethod
+    def _recreate_style(rules):
+        """Convert internal style keys to CSS property names, filtering non-CSS keys."""
+        sami_style = {}
+
+        for key, value in list(rules.items()):
+            if key in _NON_CSS_KEYS:
+                continue
+            elif key == "italics" and value is True:
+                sami_style["font-style"] = "italic"
+            elif key == "bold" and value is True:
+                sami_style["font-weight"] = "bold"
+            elif key == "underline" and value is True:
+                sami_style["text-decoration"] = "underline"
+            else:
+                sami_style[key] = value
+
+        return sami_style
diff --git a/tests/test_sami_conversion.py b/tests/test_sami_conversion.py
index cebdcf86..43787274 100644
--- a/tests/test_sami_conversion.py
+++ b/tests/test_sami_conversion.py
@@ -84,10 +84,9 @@ def test_is_relativized(
     ):
         # Absolute positioning settings (e.g. px) are converted to percentages
         caption_set = self.reader.read(sample_sami_partial_margins)
-        result = SAMIWriter(
-            video_width=VIDEO_WIDTH,
-            video_height=VIDEO_HEIGHT
-        ).write(caption_set)
+        result = SAMIWriter(video_width=VIDEO_WIDTH, video_height=VIDEO_HEIGHT).write(
+            caption_set
+        )
 
         self.assert_sami_captions_equal(sample_sami_partial_margins_relativized, result)
 
@@ -109,3 +108,94 @@ def test_webvtt_to_sami_conversion(self, sample_sami, sample_webvtt):
 
         assert isinstance(result, str)
         self.assert_sami_captions_equal(sample_sami, result)
+
+
+class TestWebVTTtoSAMIStyles(SAMITestingMixIn):
+    """Tests for WebVTT structured style/layout → SAMI conversion."""
+
+    def test_class_span(self):
+        vtt = (
+            "WEBVTT\n\n"
+            "STYLE\n"
+            "::cue(.yellow) {\n  color: yellow;\n}\n\n"
+            "00:00:01.000 --> 00:00:04.000\n"
+            "<c.yellow>Hello yellow</c>\n"
+        )
+        caption_set = WebVTTReader().read(vtt)
+        result = SAMIWriter().write(caption_set)
+
+        assert 'class="yellow"' in result
+        assert "classes" not in result
+
+    def test_multiple_css_properties(self):
+        vtt = (
+            "WEBVTT\n\n"
+            "STYLE\n"
+            "::cue(.fancy) {\n  color: red;\n}\n\n"
+            "00:00:01.000 --> 00:00:04.000\n"
+            "<c.fancy>Fancy text</c>\n"
+        )
+        caption_set = WebVTTReader().read(vtt)
+        result = SAMIWriter().write(caption_set)
+
+        assert "color:red;" in result or "color: red;" in result
+
+    def test_positioning_alignment(self):
+        vtt = "WEBVTT\n\n" "00:00:01.000 --> 00:00:04.000 align:left\n" "Left aligned\n"
+        caption_set = WebVTTReader().read(vtt)
+        result = SAMIWriter().write(caption_set)
+
+        assert "text-align:left;" in result or "text-align: left;" in result
+
+    def test_writing_direction_dropped(self):
+        vtt = (
+            "WEBVTT\n\n" "00:00:01.000 --> 00:00:04.000 vertical:rl\n" "Vertical text\n"
+        )
+        caption_set = WebVTTReader().read(vtt)
+        result = SAMIWriter().write(caption_set)
+
+        assert "writing-mode" not in result
+        assert "vertical" not in result
+        assert "Vertical text" in result
+
+    def test_plain_cue_regression(self):
+        vtt = "WEBVTT\n\n" "00:00:01.000 --> 00:00:04.000\n" "Plain caption text\n"
+        caption_set = WebVTTReader().read(vtt)
+        result = SAMIWriter().write(caption_set)
+
+        assert "Plain caption text" in result
+        assert "<sync" in result.lower()
+
+    def test_stylesheet_output(self):
+        vtt = (
+            "WEBVTT\n\n"
+            "STYLE\n"
+            "::cue(.yellow) {\n  color: yellow;\n}\n\n"
+            "00:00:01.000 --> 00:00:04.000\n"
+            "<c.yellow>Styled</c>\n"
+        )
+        caption_set = WebVTTReader().read(vtt)
+        result = SAMIWriter().write(caption_set)
+
+        assert ".yellow" in result
+        assert "color: yellow;" in result
+
+    def test_multiple_classes(self):
+        vtt = (
+            "WEBVTT\n\n"
+            "STYLE\n"
+            "::cue(.red) {\n  color: red;\n}\n\n"
+            "STYLE\n"
+            "::cue(.blue) {\n  color: blue;\n}\n\n"
+            "00:00:01.000 --> 00:00:04.000\n"
+            "<c.red>Red</c>\n\n"
+            "00:00:05.000 --> 00:00:08.000\n"
+            "<c.blue>Blue</c>\n"
+        )
+        caption_set = WebVTTReader().read(vtt)
+        result = SAMIWriter().write(caption_set)
+
+        assert ".red" in result
+        assert ".blue" in result
+        assert 'class="red"' in result
+        assert 'class="blue"' in result