Add Arabic subtitle support

Bundle an Arabic font and enable complex text layout so right-to-left
subtitles render with joined letters and correct word order.

- Add Tajawal Regular/Bold (SIL OFL) to resource/fonts. Tajawal covers
  Arabic, Latin and both digit sets, so mixed-script subtitles render
  from a single font. The font picker already discovers .ttf files, so
  no UI change is needed.
- Install libraqm0 in both Docker images. Pillow wheels no longer bundle
  Raqm but still load it at runtime; without it Pillow falls back to
  basic layout, which leaves Arabic letters unjoined and in reversed
  order even when the font has the glyphs.
- Floor the subtitle box height at the font's ascent + descent. MoviePy
  derives text height from the glyph ink box when Pillow's removed
  _multiline_spacing helper is missing, which clips fonts whose metrics
  exceed their ink height.
- Center the no-background subtitle by its visible pixels, matching what
  the background branches already did.
- Warn in the WebUI and the task log when subtitles contain right-to-left
  text but no shaping engine is available, since the failure is otherwise
  silent.

Author: MhAhmadAli

Dockerfile

@@ -26,6 +26,7 @@ RUN if [ "$DOCKER_BUILD_MIRROR" = "china" ]; then \
             echo "Attempt $i: installing system dependencies"; \
             apt-get update && apt-get install -y --no-install-recommends \
                 git \
+                libraqm0 \
                 ffmpeg && break || \
             echo "Attempt $i failed, retrying..."; \
             if [ "$DOCKER_BUILD_MIRROR" = "china" ] && [ $i -eq 3 ]; then \
@@ -35,13 +36,15 @@ RUN if [ "$DOCKER_BUILD_MIRROR" = "china" ]; then \
                 ( \
                     apt-get update && apt-get install -y --no-install-recommends \
                         git \
+                        libraqm0 \
                         ffmpeg || \
                     ( \
                         echo "Tsinghua mirror failed, switching to default Debian mirror"; \
                         sed -i 's/mirrors.tuna.tsinghua.edu.cn/deb.debian.org/g' /etc/apt/sources.list && \
                         sed -i 's/mirrors.tuna.tsinghua.edu.cn\/debian-security/security.debian.org/g' /etc/apt/sources.list; \
                         apt-get update && apt-get install -y --no-install-recommends \
                             git \
+                            libraqm0 \
                             ffmpeg; \
                     ); \
                 ); \

Dockerfile.gpu

@@ -14,6 +14,7 @@ ENV PYTHONPATH="/MoneyPrinterTurbo"
 RUN apt-get update && apt-get install -y --no-install-recommends \
         software-properties-common \
         git \
+        libraqm0 \
         ffmpeg \
         curl \
         && add-apt-repository ppa:deadsnakes/ppa \

README-en.md

@@ -231,6 +231,7 @@ 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
 
 #### ① Clone the Project
 

README-ja.md

@@ -230,6 +230,7 @@ GitHub Releases から最新の Windows 用ワンクリックパッケージを
 
 - ローカル環境へのデプロイには Python 3.11 以降が必要です
 - Windows では、プロジェクトのパスに非 ASCII 文字、特殊文字、スペースを含めないでください
+- アラビア語など右から左に書く字幕には、システムへの libraqm のインストールが必要です（Debian/Ubuntu: `apt install libraqm0`、macOS: `brew install libraqm`）。無い場合は文字が連結されず語順も逆になります。Docker イメージには同梱済みです
 
 #### ① プロジェクトをクローンする
 

README.md

@@ -237,6 +237,7 @@
 
 - 本地部署需要 Python 3.11 或更高版本
 - Windows 用户建议避免使用包含中文、特殊字符或空格的项目路径
+- 阿拉伯语等从右到左的字幕需要系统安装 libraqm（Debian/Ubuntu：`apt install libraqm0`，macOS：`brew install libraqm`）。缺少它时字母不会连写且顺序会颠倒，Docker 镜像已内置
 
 #### ① 克隆代码
 

app/services/video.py

@@ -23,7 +23,7 @@
     afx,
 )
 from moviepy.video.tools.subtitles import SubtitlesClip
-from PIL import Image, ImageDraw, ImageFont
+from PIL import Image, ImageDraw, ImageFont, features
 
 from app.config import config
 from app.models import const
@@ -968,6 +968,69 @@ def subtitle_font_supports_text(font_path: str, text: str) -> bool:
     return _subtitle_font_supports_sample(font_path, sample)
 
 
+@lru_cache(maxsize=1)
+def text_layout_supports_shaping() -> bool:
+    """
+    判断 Pillow 是否启用了 Raqm 复杂文本排版（HarfBuzz 字形整形 + FriBiDi 双向重排）。
+
+    PyPI 的 Pillow wheel 不再内置 Raqm，但运行时会 dlopen 系统的 libraqm。
+    缺少它时 Pillow 退回 BASIC 排版：阿拉伯语等文种的字母不会连写，也不会
+    按从右到左的顺序排列，即使字体本身包含字形，字幕依然无法阅读。
+    """
+    try:
+        return bool(features.check("raqm"))
+    except Exception as e:
+        logger.warning(f"failed to detect Pillow raqm support: {e}")
+        return False
+
+
+def subtitle_text_needs_shaping(text: str) -> bool:
+    """判断文本是否包含需要整形或双向重排的从右到左文字（阿拉伯语、希伯来语等）。"""
+    return any(
+        unicodedata.bidirectional(char) in {"R", "AL", "AN"}
+        for char in str(text or "")
+    )
+
+
+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,
@@ -1019,6 +1082,8 @@ def create_text_clip(subtitle_item):
         params.font_size = int(params.font_size)
         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()
         max_width = video_width * 0.9
         bg_color = resolve_subtitle_background_color()
         rounded_bg_enabled = bool(
@@ -1050,7 +1115,14 @@ def create_text_clip(subtitle_item):
         # 描边或背景色时，容易把最后一行的下半部分裁掉。这里显式传入
         # 一个更保守的高度，把行间距和额外上下留白一并算进去，保证字幕
         # 背景框与文字本身都能完整渲染出来。
-        clip_h = int(txt_height + vertical_padding + (interline * line_count))
+        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))
 
         if rounded_bg_enabled:
             # 圆角背景需要贴合文字宽度，而不是沿用 90% 视频宽度。这里先用
@@ -1131,7 +1203,7 @@ def create_text_clip(subtitle_item):
                 int(max_width),
                 clip_h,
             )
-            _clip = TextClip(
+            text_clip = TextClip(
                 text=wrapped_txt,
                 font=font_path,
                 font_size=params.font_size,
@@ -1140,8 +1212,27 @@ def create_text_clip(subtitle_item):
                 stroke_color=params.stroke_color,
                 stroke_width=params.stroke_width,
                 interline=interline,
-                size=size,
+                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,
             )
         duration = subtitle_item[0][1] - subtitle_item[0][0]
         _clip = _clip.with_start(subtitle_item[0][0])

resource/fonts/Tajawal-Bold.ttf

@@ -0,0 +1,93 @@
+Copyright 2018 Boutros International. (http://www.boutrosfonts.com)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

resource/fonts/Tajawal-OFL.txt

@@ -3,6 +3,7 @@
 import unittest
 
 import numpy as np
+from PIL import ImageFont
 
 from app.models.schema import SubtitleRequest, VideoParams
 from app.services import video
@@ -28,6 +29,7 @@ def test_all_locales_include_subtitle_background_labels(self):
             "Subtitle Background Color",
             "Subtitle Colors Are Indistinguishable",
             "Subtitle Font Does Not Support Text",
+            "Subtitle Text Shaping Unavailable",
             "No Voice",
         }
 
@@ -162,3 +164,84 @@ def test_wrap_text_keeps_closing_punctuation_with_text(self):
 
         self.assertNotIn("\n。", wrapped_text)
         self.assertIn("挡。", wrapped_text)
+
+    def test_bundled_arabic_font_covers_arabic_and_latin(self):
+        """
+        阿拉伯语字幕常混排拉丁字母和数字，因此新增字体必须同时覆盖两种字符，
+        否则同一条字幕里会出现缺字。
+        """
+        fonts_dir = Path(__file__).parent.parent.parent / "resource" / "fonts"
+        arabic_font = fonts_dir / "Tajawal-Regular.ttf"
+
+        self.assertTrue(arabic_font.exists())
+        self.assertTrue((fonts_dir / "Tajawal-Bold.ttf").exists())
+        self.assertTrue(
+            video.subtitle_font_supports_text(str(arabic_font), "الذكاء الاصطناعي")
+        )
+        self.assertTrue(
+            video.subtitle_font_supports_text(
+                str(arabic_font), "MoneyPrinterTurbo 2026"
+            )
+        )
+        self.assertFalse(
+            video.subtitle_font_supports_text(
+                str(fonts_dir / "MicrosoftYaHeiBold.ttc"), "الذكاء الاصطناعي"
+            )
+        )
+
+    def test_detects_text_that_requires_bidi_shaping(self):
+        """只有从右到左的文字需要 Raqm 整形，中英文不应触发额外提示。"""
+        self.assertTrue(video.subtitle_text_needs_shaping("الذكاء الاصطناعي"))
+        self.assertTrue(video.subtitle_text_needs_shaping("مرحبا MoneyPrinterTurbo"))
+        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,
+        )