Address review feedback on Arabic subtitle support

- Add the shaping warning key to the new Italian locale so every WebUI
  language carries it after rebasing onto main.
- Scope the "no shaping engine" warning to each generate_video() call
  instead of caching it for the whole process, so every task that renders
  right-to-left subtitles records the warning.
- Drop the subtitle height floor and the no-background centering change.
  They alter subtitle geometry for every language, and the bundled Arabic
  font does not need them, so they belong in their own change with visual
  regression coverage. Subtitle layout is now identical to main.
- Add the Homebrew library directory to DYLD_LIBRARY_PATH in webui.sh on
  macOS. Pillow dlopens libraqm/libfribidi, which Homebrew installs outside
  the default search path, so raqm stayed disabled without it.
- Document the shaping requirement per platform, including that the Windows
  Pillow wheel needs an external FriBiDi DLL that the one-click package does
  not ship.

Author: MhAhmadAli

README-en.md

@@ -231,7 +231,11 @@ Use the local setup or Docker instructions below.
 
 - Local deployment requires Python 3.11 or later
 - On Windows, avoid project paths containing non-ASCII characters, special characters, or spaces
-- Right-to-left subtitles such as Arabic need libraqm installed on the system (Debian/Ubuntu: `apt install libraqm0`, macOS: `brew install libraqm`). Without it letters are not joined and word order is reversed; the Docker images already include it
+- Right-to-left subtitles such as Arabic need Pillow's Raqm layout engine. Without it letters are not joined and word order is reversed:
+    - Docker: already included in the images, nothing to do
+    - Linux: `apt install libraqm0`
+    - macOS: `brew install libraqm`. Homebrew's libraries are not on the default search path, so `webui.sh` adds `DYLD_LIBRARY_PATH` automatically; if you launch Streamlit yourself, export `DYLD_LIBRARY_PATH="$(brew --prefix)/lib:$DYLD_LIBRARY_PATH"` first
+    - Windows: the official Pillow wheel needs an external FriBiDi DLL on PATH, which the one-click package does not ship. Until it does, a local Windows install cannot render right-to-left subtitles correctly — use Docker instead
 
 #### ① Clone the Project
 

README-ja.md

@@ -230,7 +230,11 @@ GitHub Releases から最新の Windows 用ワンクリックパッケージを
 
 - ローカル環境へのデプロイには Python 3.11 以降が必要です
 - Windows では、プロジェクトのパスに非 ASCII 文字、特殊文字、スペースを含めないでください
-- アラビア語など右から左に書く字幕には、システムへの libraqm のインストールが必要です（Debian/Ubuntu: `apt install libraqm0`、macOS: `brew install libraqm`）。無い場合は文字が連結されず語順も逆になります。Docker イメージには同梱済みです
+- アラビア語など右から左に書く字幕には、Pillow の Raqm 組版エンジンが必要です。無い場合は文字が連結されず語順も逆になります:
+    - Docker: イメージに同梱済みで、追加作業は不要です
+    - Linux: `apt install libraqm0`
+    - macOS: `brew install libraqm`。Homebrew のライブラリは既定の検索パスに無いため、`webui.sh` が `DYLD_LIBRARY_PATH` を自動で追加します。Streamlit を手動で起動する場合は `export DYLD_LIBRARY_PATH="$(brew --prefix)/lib:$DYLD_LIBRARY_PATH"` を先に実行してください
+    - Windows: 公式の Pillow wheel は PATH 上に別途 FriBiDi DLL を必要としますが、ワンクリックパッケージには同梱されていません。同梱されるまで Windows のローカル環境では右から左の字幕を正しく描画できないため、Docker の利用を推奨します
 
 #### ① プロジェクトをクローンする
 

README.md

@@ -237,7 +237,11 @@
 
 - 本地部署需要 Python 3.11 或更高版本
 - Windows 用户建议避免使用包含中文、特殊字符或空格的项目路径
-- 阿拉伯语等从右到左的字幕需要系统安装 libraqm（Debian/Ubuntu：`apt install libraqm0`，macOS：`brew install libraqm`）。缺少它时字母不会连写且顺序会颠倒，Docker 镜像已内置
+- 阿拉伯语等从右到左的字幕需要 Pillow 启用 Raqm 排版引擎，缺少时字母不会连写、词序也会颠倒：
+    - Docker：镜像已内置，无需额外操作
+    - Linux：`apt install libraqm0`
+    - macOS：`brew install libraqm`。Homebrew 的动态库不在默认搜索路径里，`webui.sh` 会自动补上 `DYLD_LIBRARY_PATH`；如果你手动启动 Streamlit，需要自行 `export DYLD_LIBRARY_PATH="$(brew --prefix)/lib:$DYLD_LIBRARY_PATH"`
+    - Windows：官方 Pillow wheel 需要额外的 FriBiDi DLL 位于 PATH 中，一键包并未内置。在补齐之前，Windows 本地部署无法正确渲染从右到左的字幕，建议改用 Docker
 
 #### ① 克隆代码
 

app/services/video.py

@@ -992,45 +992,6 @@ def subtitle_text_needs_shaping(text: str) -> bool:
     )
 
 
-def _subtitle_text_block_height(
-    font_path: str,
-    font_size: int,
-    stroke_width: int,
-    line_count: int,
-    ink_height: int,
-) -> int:
-    """
-    计算多行字幕文字实际需要的像素高度。
-
-    MoviePy 2.2.1 依赖 Pillow 的私有方法 `_multiline_spacing` 计算文本高度，
-    该方法在新版 Pillow 中已被移除，于是 MoviePy 退回使用字形墨迹包围盒
-    （`bottom - top`）。墨迹高度会明显小于字体自身的 ascent + descent，
-    而 MoviePy 仍按 ascent 定位基线，导致 ascent/descent 较大的字体（阿拉伯语
-    字体尤为典型，也包括已内置的 Charm、微软雅黑）下方被裁切。
-
-    这里改用 MoviePy 文档中声明的公式 `ascent + descent + 2 * stroke_width`
-    作为单行高度下限，无论 MoviePy 走哪个分支都能留出完整的绘制空间；对
-    ascent/descent 较小的中文字体则维持原有的墨迹高度，不改变既有观感。
-    """
-    try:
-        ascent, descent = ImageFont.truetype(font_path, font_size).getmetrics()
-        metric_height = (ascent + descent) * max(1, line_count) + 2 * stroke_width
-    except Exception as e:
-        logger.warning(f"failed to read subtitle font metrics: {font_path}, {e}")
-        metric_height = 0
-    return int(max(ink_height, metric_height))
-
-
-@lru_cache(maxsize=1)
-def _warn_missing_text_shaping() -> None:
-    """整段任务只提示一次，避免逐条字幕刷屏。"""
-    logger.warning(
-        "subtitle contains right-to-left text but Pillow has no Raqm layout engine; "
-        "letters will not be joined and word order will be reversed. "
-        "install libraqm (Debian/Ubuntu: libraqm0, macOS: brew install libraqm)"
-    )
-
-
 def generate_video(
     video_path: str,
     audio_path: str,
@@ -1070,6 +1031,22 @@ def generate_video(
 
         logger.info(f"  ⑤ font: {font_path}")
 
+    # 缺少 Raqm 是环境级问题，但提示必须按任务给出：整个进程只提示一次会让
+    # 后续任务的日志完全看不到这条关键信息。这里用单次任务内的标志位收敛，
+    # 既不会逐条字幕刷屏，也保证每次合成都留下记录。
+    missing_shaping_warned = False
+
+    def warn_missing_text_shaping_once():
+        nonlocal missing_shaping_warned
+        if missing_shaping_warned:
+            return
+        missing_shaping_warned = True
+        logger.warning(
+            "subtitle contains right-to-left text but Pillow has no Raqm layout "
+            "engine; letters will not be joined and word order will be reversed. "
+            "install libraqm (Debian/Ubuntu: libraqm0, macOS: brew install libraqm)"
+        )
+
     def resolve_subtitle_background_color():
         # 兼容历史参数：API 里 `text_background_color` 既可能是布尔值，
         # 也可能是实际颜色字符串。统一在这里归一化，避免把 True/False
@@ -1083,7 +1060,7 @@ def create_text_clip(subtitle_item):
         params.stroke_width = int(params.stroke_width)
         phrase = subtitle_item[1]
         if subtitle_text_needs_shaping(phrase) and not text_layout_supports_shaping():
-            _warn_missing_text_shaping()
+            warn_missing_text_shaping_once()
         max_width = video_width * 0.9
         bg_color = resolve_subtitle_background_color()
         rounded_bg_enabled = bool(
@@ -1115,14 +1092,7 @@ def create_text_clip(subtitle_item):
         # 描边或背景色时，容易把最后一行的下半部分裁掉。这里显式传入
         # 一个更保守的高度，把行间距和额外上下留白一并算进去，保证字幕
         # 背景框与文字本身都能完整渲染出来。
-        text_block_height = _subtitle_text_block_height(
-            font_path=font_path,
-            font_size=params.font_size,
-            stroke_width=params.stroke_width,
-            line_count=line_count,
-            ink_height=int(txt_height),
-        )
-        clip_h = int(text_block_height + vertical_padding + (interline * line_count))
+        clip_h = int(txt_height + vertical_padding + (interline * line_count))
 
         if rounded_bg_enabled:
             # 圆角背景需要贴合文字宽度，而不是沿用 90% 视频宽度。这里先用
@@ -1203,7 +1173,7 @@ def create_text_clip(subtitle_item):
                 int(max_width),
                 clip_h,
             )
-            text_clip = TextClip(
+            _clip = TextClip(
                 text=wrapped_txt,
                 font=font_path,
                 font_size=params.font_size,
@@ -1212,27 +1182,8 @@ def create_text_clip(subtitle_item):
                 stroke_color=params.stroke_color,
                 stroke_width=params.stroke_width,
                 interline=interline,
-                size=(int(max_width), None),
-                text_align="center",
-                margin=(0, text_clip_margin_y),
-            )
-            size = (size[0], max(size[1], text_clip.h))
-            # 无背景字幕同样需要按可见像素居中。MoviePy 先按墨迹高度居中、
-            # 再按 ascent 落基线，字形墨迹没有顶到 ascender 时文字就会偏离
-            # 画布中心；带背景的分支早已用透明底板 + 可见居中修正，这里沿用
-            # 同一套做法，只是底板完全透明，避免阿拉伯语等大 ascent/descent
-            # 字体的字幕整体偏上。
-            transparent_canvas = _rounded_subtitle_background_clip(
-                width=size[0],
-                height=size[1],
-                color="#000000",
-                alpha=0,
-                radius=0,
-            )
-            text_position = _get_visible_center_position(text_clip, size[0], size[1])
-            _clip = CompositeVideoClip(
-                [transparent_canvas, text_clip.with_position(text_position)],
                 size=size,
+                text_align="center",
             )
         duration = subtitle_item[0][1] - subtitle_item[0][0]
         _clip = _clip.with_start(subtitle_item[0][0])

test/services/test_subtitle_background_settings.py

@@ -3,7 +3,6 @@
 import unittest
 
 import numpy as np
-from PIL import ImageFont
 
 from app.models.schema import SubtitleRequest, VideoParams
 from app.services import video
@@ -196,52 +195,3 @@ def test_detects_text_that_requires_bidi_shaping(self):
         self.assertFalse(video.subtitle_text_needs_shaping("人工智能改变生活"))
         self.assertFalse(video.subtitle_text_needs_shaping("Artificial intelligence"))
         self.assertFalse(video.subtitle_text_needs_shaping(""))
-
-    def test_text_block_height_reserves_room_for_font_metrics(self):
-        """
-        MoviePy 依赖的 Pillow 私有方法已被移除，导致文本高度退化成墨迹高度，
-        ascent/descent 较大的字体下方会被裁切。字幕高度必须以字体自身的
-        ascent + descent 为下限，同时保留墨迹更高时的原有取值。
-        """
-        fonts_dir = Path(__file__).parent.parent.parent / "resource" / "fonts"
-        arabic_font = str(fonts_dir / "Tajawal-Regular.ttf")
-        ascent, descent = ImageFont.truetype(arabic_font, 60).getmetrics()
-
-        single_line = video._subtitle_text_block_height(
-            font_path=arabic_font,
-            font_size=60,
-            stroke_width=1,
-            line_count=1,
-            ink_height=1,
-        )
-        two_lines = video._subtitle_text_block_height(
-            font_path=arabic_font,
-            font_size=60,
-            stroke_width=1,
-            line_count=2,
-            ink_height=1,
-        )
-        ink_taller_than_metrics = video._subtitle_text_block_height(
-            font_path=arabic_font,
-            font_size=60,
-            stroke_width=1,
-            line_count=1,
-            ink_height=9999,
-        )
-
-        self.assertEqual(single_line, ascent + descent + 2)
-        self.assertEqual(two_lines, (ascent + descent) * 2 + 2)
-        self.assertEqual(ink_taller_than_metrics, 9999)
-
-    def test_text_block_height_falls_back_when_font_is_unreadable(self):
-        """字体探测失败时不能让字幕高度归零，应至少退回墨迹高度。"""
-        self.assertEqual(
-            video._subtitle_text_block_height(
-                font_path="/nonexistent/font.ttf",
-                font_size=60,
-                stroke_width=1,
-                line_count=1,
-                ink_height=88,
-            ),
-            88,
-        )

webui.sh

@@ -16,6 +16,23 @@ export PYTHONPATH="$CURRENT_DIR${PYTHONPATH:+:$PYTHONPATH}"
 MPT_WEBUI_HOST="${MPT_WEBUI_HOST:-127.0.0.1}"
 MPT_WEBUI_PORT="${MPT_WEBUI_PORT:-8501}"
 
+# macOS 上 Pillow 在运行时 dlopen libraqm/libfribidi，但 Homebrew 的动态库目录
+# 不在默认搜索路径里，Pillow 会直接报告 raqm=False，阿拉伯语等从右到左的字幕
+# 就不会连写、词序也会颠倒。这里在检测到 Homebrew 已安装相关动态库时补上
+# DYLD_LIBRARY_PATH，Intel 与 Apple Silicon 的默认前缀都会尝试。
+if [ "$(uname -s)" = "Darwin" ]; then
+  for MPT_BREW_LIB in "$(brew --prefix 2>/dev/null)/lib" /opt/homebrew/lib /usr/local/lib; do
+    if [ -e "$MPT_BREW_LIB/libraqm.dylib" ] || [ -e "$MPT_BREW_LIB/libfribidi.dylib" ]; then
+      case ":${DYLD_LIBRARY_PATH:-}:" in
+        *":$MPT_BREW_LIB:"*) ;;
+        *) export DYLD_LIBRARY_PATH="$MPT_BREW_LIB${DYLD_LIBRARY_PATH:+:$DYLD_LIBRARY_PATH}" ;;
+      esac
+      break
+    fi
+  done
+  unset MPT_BREW_LIB
+fi
+
 if [ -x "$CURRENT_DIR/.venv/bin/python" ]; then
   PORT_CHECK_CMD="$CURRENT_DIR/.venv/bin/python"
   set -- "$CURRENT_DIR/.venv/bin/python" -m streamlit

webui/i18n/it.json

@@ -175,6 +175,7 @@
     "Rounded Subtitle Background Help": "Disabilitato per impostazione predefinita. Se abilitato, lo sfondo dei sottotitoli utilizza uno stile arrotondato e traslucido che si adatta meglio alla larghezza del testo.",
     "Subtitle Colors Are Indistinguishable": "Il testo e lo sfondo dei sottotitoli usano lo stesso colore, quindi i sottotitoli potrebbero non essere visibili.",
     "Subtitle Font Does Not Support Text": "Il carattere selezionato per i sottotitoli non supporta alcuni caratteri del testo, quindi alcuni sottotitoli potrebbero mancare.",
+    "Subtitle Text Shaping Unavailable": "I sottotitoli scritti da destra a sinistra come l'arabo richiedono il motore di composizione del testo Raqm, che qui non è disponibile: le lettere non verranno unite e l'ordine delle parole risulterà invertito. Installa libraqm (Debian/Ubuntu: libraqm0, macOS: brew install libraqm).",
     "Restore Default Subtitle Settings": "Ripristina valori predefiniti dei sottotitoli",
     "Default Subtitle Settings Restored": "Impostazioni predefinite dei sottotitoli ripristinate",
     "Generate Video": "Genera video",