."""
+ 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 += " 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 " 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), 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 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
"
+ 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""
+ 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""
+
+ def handle_entityref(self, name):
+ """Convert named HTML entities to characters; preserve > and <."""
+ 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 "
(break), // (style),
+ and (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 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