Files
ersatztv/ErsatzTV.Infrastructure/Streaming/Graphics/Text/TextElement.cs
T
timothy 0ab52ad71c feat(732): give the On Now / Next overlay a background box and turn it on by default
Part 1 - background box. TextGraphicsElement gains element-level background_color,
background_opacity_percent, background_padding, background_corner_radius, border_color and
border_width; TextElement draws a rounded rect behind the text block and insets the text into it.
Element level rather than per-style because the engine lays the whole element out as one
RichTextKit TextBlock and rasterises it into one bitmap, so one box per element is the only shape
the renderer can express. width_percent keeps bounding the visible element, so the insets are
subtracted from the text's wrap/scale budget.

The seeded on-now-next.yml adopts it. The halo drops from 2px to 1px rather than to zero, and the
box carries a low-alpha white border: rendered against real frames, a 65% black fill is legible on
bright and midtone content but vanishes entirely into dark content, which is why the issue asked
for an *outlined* box. The halo still matters because the fill is translucent.

Because #74's seeder writes the template only when absent, an already-seeded install would never
have seen any of this. GraphicsElementSeeder now keeps every default it has shipped as a verbatim
fingerprint and rewrites the file only when it still matches one (line-endings normalised), so an
untouched install upgrades and an operator-edited one is left alone. The V1 fingerprint was checked
byte-for-byte against the live install before being trusted - a fingerprint that matches nothing in
the field is a permanent silent no-op.

Part 2 - on by default. New channels get the built-in element from CreateChannelHandler (CreateChannel
carries no graphics field and the SPA's channel editor is update-only, so the server is the only
place a create-time default can live). Pre-existing channels get a one-time AttachOnNowNextByDefault
backfill. The marker is written on the first run even when nothing was attached: the tempting
alternative - stay armed until the element row exists - would fire on a later boot and re-attach the
overlay to a channel the operator had cleared in between. HLS Direct is excluded at both sites,
where the overlay cannot render at all.

Resolves the issue's open question: [vge] in a filter graph does not imply a graphics element is
bound. Watermarks fall back onto the graphics engine whenever they cannot use ffmpeg's native
overlay shortcut, so a watermark alone produces that stage.

Tests assert rendered pixels, because every failure mode here is a silent no-op that a model-level
test cannot see. 13 clause mutations were executed against them; each reddened only its own clause.

Decisions-Edit: yes
Refs: #732
2026-08-26 20:37:06 +02:00

460 lines
15 KiB
C#

using System.Text.RegularExpressions;
using ErsatzTV.Core.Graphics;
using ErsatzTV.Core.Interfaces.Streaming;
using Microsoft.Extensions.Logging;
using NCalc;
using SkiaSharp;
using RichTextKit = Topten.RichTextKit;
namespace ErsatzTV.Infrastructure.Streaming.Graphics;
public partial class TextElement(
GraphicsEngineFonts graphicsEngineFonts,
TextGraphicsElement textElement,
ILogger logger)
: GraphicsElement, IDisposable
{
private static readonly Regex StylePattern = StyleRegex();
private SKBitmap _image;
private SKPointI _location;
private Option<Expression> _maybeOpacityExpression;
private float _opacity;
public override int ZIndex { get; } = textElement.ZIndex ?? 0;
public override string DebugKey { get; } = $"Text {textElement.DebugName()}";
public void Dispose()
{
GC.SuppressFinalize(this);
_image?.Dispose();
_image = null;
}
public override Task InitializeAsync(GraphicsEngineContext context, CancellationToken cancellationToken)
{
try
{
if (!string.IsNullOrWhiteSpace(textElement.OpacityExpression))
{
var expression = new Expression(textElement.OpacityExpression);
expression.EvaluateFunction += OpacityExpressionHelper.EvaluateFunction;
_maybeOpacityExpression = expression;
}
else
{
_opacity = (textElement.OpacityPercent ?? 100) / 100.0f;
}
if (!string.IsNullOrWhiteSpace(textElement.IncludeFontsFrom))
{
if (Directory.Exists(textElement.IncludeFontsFrom))
{
graphicsEngineFonts.LoadFonts(textElement.IncludeFontsFrom);
}
else
{
logger.LogWarning(
"include_fonts_from path {Directory} does not exist",
textElement.IncludeFontsFrom);
}
}
BackgroundBox box = BuildBackgroundBox();
RichTextKit.TextBlock textBlock = BuildTextBlock(textElement.Text);
// Padding and border sit OUTSIDE the laid-out text on every side, so they shrink the
// space the text may occupy and grow the bitmap that holds it. Zero when there is no
// box, which reproduces the pre-#732 geometry exactly.
float inset = box?.Inset ?? 0f;
if (textElement.WidthPercent.HasValue)
{
var maxWidth = (float)Math.Round(textElement.WidthPercent.Value / 100.0 * context.FrameSize.Width);
// width_percent bounds the ELEMENT, so the text gets what is left after the insets.
float textMaxWidth = Math.Max(1f, maxWidth - (2 * inset));
switch (textElement.Fit)
{
case TextFit.Wrap:
textBlock.MaxWidth = textMaxWidth;
break;
case TextFit.Scale:
FitTextBlock(textBlock, textMaxWidth);
break;
}
}
var insetPixels = (int)Math.Ceiling(inset);
_image = new SKBitmap(
(int)Math.Ceiling(textBlock.MeasuredWidth) + (2 * insetPixels),
(int)Math.Ceiling(textBlock.MeasuredHeight) + (2 * insetPixels));
using (var canvas = new SKCanvas(_image))
{
canvas.Clear(SKColors.Transparent);
if (box is not null)
{
DrawBackgroundBox(canvas, box, _image.Width, _image.Height);
}
textBlock.Paint(canvas, new SKPoint(insetPixels, insetPixels));
}
var horizontalMargin =
(int)Math.Round((textElement.HorizontalMarginPercent ?? 0) / 100.0 * context.FrameSize.Width);
var verticalMargin =
(int)Math.Round((textElement.VerticalMarginPercent ?? 0) / 100.0 * context.FrameSize.Height);
_location = CalculatePosition(
textElement.Location,
context.FrameSize.Width,
context.FrameSize.Height,
_image.Width,
_image.Height,
horizontalMargin,
verticalMargin);
}
catch (Exception ex)
{
IsFinished = true;
logger.LogWarning(ex, "Failed to initialize text element; will disable for this content");
}
return Task.CompletedTask;
}
public override ValueTask<Option<PreparedElementImage>> PrepareImage(
TimeSpan timeOfDay,
TimeSpan contentTime,
TimeSpan contentTotalTime,
TimeSpan channelTime,
CancellationToken cancellationToken)
{
float opacity = _opacity;
foreach (Expression expression in _maybeOpacityExpression)
{
opacity = OpacityExpressionHelper.GetOpacity(
expression,
timeOfDay,
contentTime,
contentTotalTime,
channelTime);
}
return opacity == 0
? ValueTask.FromResult(Option<PreparedElementImage>.None)
: new ValueTask<Option<PreparedElementImage>>(new PreparedElementImage(_image, _location, opacity, ZIndex, false));
}
// A background box is drawn only when a colour actually parses. An unparseable colour is
// warned about and skipped rather than substituted, so a typo never silently changes the
// look into something that appears deliberate.
private BackgroundBox BuildBackgroundBox()
{
SKColor? fill = ParseOptionalColor(textElement.BackgroundColor, "background_color");
if (fill.HasValue)
{
fill = ApplyOpacityPercent(fill.Value, textElement.BackgroundOpacityPercent);
}
SKColor? border = ParseOptionalColor(textElement.BorderColor, "border_color");
// A border colour with no explicit width means a hairline border, not an invisible one:
// "border_color set, nothing drawn" is the more confusing of the two readings.
var borderWidth = (float)Math.Max(0, textElement.BorderWidth ?? 1);
if (!border.HasValue)
{
borderWidth = 0;
}
if (!fill.HasValue && borderWidth <= 0)
{
return null;
}
return new BackgroundBox(
fill,
border,
borderWidth,
(float)Math.Max(0, textElement.BackgroundCornerRadius ?? 0),
(float)Math.Max(0, textElement.BackgroundPadding ?? 0));
}
private SKColor? ParseOptionalColor(string value, string fieldName)
{
if (string.IsNullOrWhiteSpace(value))
{
return null;
}
if (SKColor.TryParse(value, out SKColor parsed))
{
return parsed;
}
logger.LogWarning(
"Unable to parse {Field} value {Value}; that part of the background box will not be drawn",
fieldName,
value);
return null;
}
private static SKColor ApplyOpacityPercent(SKColor color, int? opacityPercent)
{
if (opacityPercent is not { } percent)
{
return color;
}
int clamped = Math.Clamp(percent, 0, 100);
return color.WithAlpha((byte)Math.Round(color.Alpha * clamped / 100.0));
}
private static void DrawBackgroundBox(SKCanvas canvas, BackgroundBox box, int width, int height)
{
// Skia strokes centred on the path, so half the border would fall outside the bitmap and
// be clipped. Inset the rect by half the width to keep the whole border visible.
float half = box.BorderWidth / 2f;
var rect = new SKRect(half, half, width - half, height - half);
// A radius larger than half the shorter side is not expressible as a rounded rect.
float radius = Math.Min(box.CornerRadius, Math.Min(rect.Width, rect.Height) / 2f);
radius = Math.Max(0, radius);
if (box.Fill is { } fill)
{
using var fillPaint = new SKPaint
{
Color = fill,
Style = SKPaintStyle.Fill,
IsAntialias = true
};
canvas.DrawRoundRect(rect, radius, radius, fillPaint);
}
if (box.Border is { } border && box.BorderWidth > 0)
{
using var borderPaint = new SKPaint
{
Color = border,
Style = SKPaintStyle.Stroke,
StrokeWidth = box.BorderWidth,
IsAntialias = true
};
canvas.DrawRoundRect(rect, radius, radius, borderPaint);
}
}
private sealed record BackgroundBox(
SKColor? Fill,
SKColor? Border,
float BorderWidth,
float CornerRadius,
float Padding)
{
public float Inset => Padding + BorderWidth;
}
private RichTextKit.TextBlock BuildTextBlock(string textToRender)
{
var textBlock = new RichTextKit.TextBlock
{
FontMapper = graphicsEngineFonts.Mapper,
Alignment = textElement.Align switch
{
TextAlignment.Center => RichTextKit.TextAlignment.Center,
TextAlignment.Right => RichTextKit.TextAlignment.Right,
TextAlignment.Left => RichTextKit.TextAlignment.Left,
_ => RichTextKit.TextAlignment.Auto
}
};
(Dictionary<string, RichTextKit.Style> styles, RichTextKit.Style baseStyle) = BuildTextStyles();
var lastIndex = 0;
foreach (Match match in StylePattern.Matches(textToRender))
{
// unstyled text before match
if (match.Index > lastIndex)
{
textBlock.AddText(textToRender.AsSpan(lastIndex, match.Index - lastIndex), baseStyle);
}
string styleName = match.Groups[1].Value;
string innerText = match.Groups[2].Value;
if (styles.TryGetValue(styleName, out RichTextKit.Style style))
{
textBlock.AddText(innerText, style);
}
else
{
textBlock.AddText(match.Value, baseStyle);
}
lastIndex = match.Index + match.Length;
}
// unstyled text after match
if (lastIndex < textToRender.Length)
{
textBlock.AddText(textToRender.AsSpan(lastIndex), baseStyle);
}
return textBlock;
}
private (Dictionary<string, RichTextKit.Style>, RichTextKit.Style) BuildTextStyles()
{
var styles = new Dictionary<string, RichTextKit.Style>();
StyleDefinition baseStyleDef = textElement.Styles.Find(s => s.Name == textElement.BaseStyle);
if (baseStyleDef == null)
{
throw new InvalidOperationException(
$"The specified base_style '{textElement.BaseStyle}' was not found in the styles list.");
}
foreach (StyleDefinition s in textElement.Styles)
{
// start with base and merge in additional settings
RichTextKit.Style finalStyle = RichTextStyleFromDef(baseStyleDef);
finalStyle.FontFamily = s.FontFamily ?? finalStyle.FontFamily;
finalStyle.FontItalic = s.FontItalic ?? finalStyle.FontItalic;
finalStyle.FontSize = s.FontSize ?? finalStyle.FontSize;
finalStyle.FontWeight = s.FontWeight ?? finalStyle.FontWeight;
finalStyle.LetterSpacing = s.LetterSpacing ?? finalStyle.LetterSpacing;
finalStyle.LineHeight = s.LineHeight ?? finalStyle.LineHeight;
if (s.TextColor != null && SKColor.TryParse(s.TextColor, out SKColor parsedColor))
{
finalStyle.TextColor = parsedColor;
}
styles[s.Name] = finalStyle;
}
return (styles, RichTextStyleFromDef(baseStyleDef));
RichTextKit.Style RichTextStyleFromDef(StyleDefinition def)
{
var style = new RichTextKit.Style
{
FontFamily = def.FontFamily,
FontItalic = def.FontItalic ?? false,
TextColor = SKColor.TryParse(def.TextColor, out SKColor color) ? color : SKColors.White
};
if (SKColor.TryParse(def.HaloColor, out SKColor parsedHaloColor))
{
style.HaloColor = parsedHaloColor;
}
foreach (float haloWidth in Optional(def.HaloWidth))
{
style.HaloWidth = haloWidth;
}
foreach (float haloBlur in Optional(def.HaloBlur))
{
style.HaloBlur = haloBlur;
}
foreach (float fontSize in Optional(def.FontSize))
{
style.FontSize = fontSize;
}
foreach (int fontWeight in Optional(def.FontWeight))
{
style.FontWeight = fontWeight;
}
foreach (float letterSpacing in Optional(def.LetterSpacing))
{
style.LetterSpacing = letterSpacing;
}
foreach (float lineHeight in Optional(def.LineHeight))
{
style.LineHeight = lineHeight;
}
return style;
}
}
private static void FitTextBlock(RichTextKit.TextBlock block, float maxWidth)
{
if (block.MeasuredWidth <= maxWidth)
{
return;
}
var originalContent = block.StyleRuns
.Select(run => (run.ToString(), run.Style))
.ToList();
float scale = maxWidth / block.MeasuredWidth;
const float MIN_FONT_SIZE = 5.0f;
while (true)
{
block.Clear();
var isAtMinSize = false;
foreach ((string text, RichTextKit.IStyle style) in originalContent)
{
var newStyle = new RichTextKit.Style
{
FontFamily = style.FontFamily,
FontItalic = style.FontItalic,
FontSize = style.FontSize,
FontWidth = style.FontWidth,
FontWeight = style.FontWeight,
LetterSpacing = style.LetterSpacing,
TextColor = style.TextColor
};
float newSize = newStyle.FontSize * scale;
if (newSize < MIN_FONT_SIZE)
{
newSize = MIN_FONT_SIZE;
isAtMinSize = true;
}
newStyle.FontSize = newSize;
block.AddText(text, newStyle);
}
if (block.MeasuredWidth <= maxWidth)
{
break;
}
if (isAtMinSize)
{
break;
}
scale -= 0.01f;
}
}
[GeneratedRegex(@"\[(\w+)\](.*?)\[/\1\]")]
private static partial Regex StyleRegex();
}