[Bug 297316] multimedia/jellyfin: Jellyfin unable to load shared library 'libHarfBuzzSharp'

https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=297316

            Bug ID: 297316
           Summary: multimedia/jellyfin: Jellyfin unable to load shared
                    library 'libHarfBuzzSharp'
           Product: Ports & Packages
           Version: Latest
          Hardware: amd64
                OS: Any
            Status: New
          Severity: Affects Only Me
          Priority: ---
         Component: Individual Port(s)
          Assignee: [email protected]
          Reporter: [email protected]
             Flags: maintainer-feedback?([email protected])
          Assignee: [email protected]

Created attachment 273508
  --> https://bugs.freebsd.org/bugzilla/attachment.cgi?id=273508&action=edit
patch for libskiasharp to also build libharfbuzzsharp

Summary: Jellyfin fails to generate dynamic images containing text overlay.
This is caused by a missing system font and a missing .NET wrapper for HarfBuzz
(libHarfBuzzSharp). The issue is resolved by installing the dejavu font and
building libHarfBuzzSharp via the libskiasharp port.

I've been using Jellyfin with VA-API acceleration in a jail for several months
happily, so first: thanks for making that possible! I did run into one problem
that I think might affect other folks, so I wanted to report it here in case
that's correct. I know there's been recent Jellyfin work related to SkiaSharp
in bug #290460, so also wanted to call that out up front.

I first noticed that Jellyfin was not automatically generating the images for
my media groups: "Collections", "Movies", "Shows". On my previous Jellyfin
host, which ran Linux, it would automatically generate an image for each media
type, which notably included text overlaid on whatever artwork it randomly
chose from the media type. Other artwork showed up just fine. I tracked down
this error in Jellyfin's log whenever it tried to generate the problematic
artwork:

>>>
[2026-07-10 01:15:26.695 -04:00] [ERR] Error in "Dynamic Image Provider"
System.ArgumentNullException: Value cannot be null. (Parameter 'typeface')
   at SkiaSharp.HarfBuzz.SKShaper..ctor(SKTypeface typeface)
   at SkiaSharp.HarfBuzz.CanvasExtensions.DrawShapedText(SKCanvas canvas,
String text, Single x, Single y, SKTextAlign textAlign, SKFont font, SKPaint
paint)
   at Jellyfin.Drawing.Skia.StripCollageBuilder.DrawText(SKCanvas canvas,
Single x, Single y, String text, SKPaint textPaint, SKFont textFont, Boolean
isRtl)
   at
Jellyfin.Drawing.Skia.StripCollageBuilder.BuildThumbCollageBitmap(IReadOnlyList`1
paths, Int32 width, Int32 height, String libraryName)
   at
Jellyfin.Drawing.Skia.StripCollageBuilder.BuildThumbCollage(IReadOnlyList`1
paths, String outputPath, Int32 width, Int32 height, String libraryName)
   at Jellyfin.Drawing.Skia.SkiaEncoder.CreateImageCollage(ImageCollageOptions
options, String libraryName)
   at Jellyfin.Drawing.ImageProcessor.CreateImageCollage(ImageCollageOptions
options, String libraryName)
   at
Emby.Server.Implementations.Images.BaseDynamicImageProvider`1.CreateCollage(BaseItem
primaryItem, IEnumerable`1 items, String outputPath, Int32 width, Int32 height)
   at
Emby.Server.Implementations.Images.BaseDynamicImageProvider`1.CreateThumbCollage(BaseItem
primaryItem, IEnumerable`1 items, String outputPath, Int32 width, Int32 height)
   at
Emby.Server.Implementations.Images.CollectionFolderImageProvider.CreateImage(BaseItem
item, IReadOnlyCollection`1 itemsWithImages, String outputPathWithoutExtension,
ImageType imageType, Int32 imageIndex)
   at
Emby.Server.Implementations.Images.BaseDynamicImageProvider`1.FetchToFileInternal(BaseItem
item, IReadOnlyList`1 itemsWithImages, ImageType imageType, CancellationToken
cancellationToken)
   at
Emby.Server.Implementations.Images.BaseDynamicImageProvider`1.FetchAsync(T
item, MetadataRefreshOptions options, CancellationToken cancellationToken)
   at
MediaBrowser.Providers.Manager.MetadataService`2.RunCustomProvider(ICustomMetadataProvider`1
provider, TItemType item, String logName, MetadataRefreshOptions options,
RefreshResult refreshResult, CancellationToken cancellationToken)
<<<

I resolved this by installing the "dejavu" package, but it was replaced by a
new error:

>>>
[2026-07-11 01:45:02.966 -04:00] [ERR] Error in "Dynamic Image Provider"
System.DllNotFoundException: Unable to load shared library 'libHarfBuzzSharp'
or one of its dependencies. In order to help diagnose loading problems,
consider using a tool like strace. If you're using glibc, consider setting the
LD_DEBUG environment variable: 
Cannot open "/usr/local/jellyfin/libHarfBuzzSharp.so"
Shared object "libHarfBuzzSharp.so" not found, required by "jellyfin"
Cannot open "/usr/local/jellyfin/liblibHarfBuzzSharp.so"
Shared object "liblibHarfBuzzSharp.so" not found, required by "jellyfin"
Cannot open "/usr/local/jellyfin/libHarfBuzzSharp"
Shared object "libHarfBuzzSharp" not found, required by "jellyfin"
Cannot open "/usr/local/jellyfin/liblibHarfBuzzSharp"
Shared object "liblibHarfBuzzSharp" not found, required by "jellyfin"

   at HarfBuzzSharp.HarfBuzzApi.hb_blob_create(Void* data, UInt32 length,
MemoryMode mode, Void* user_data, Void* destroy)
   at HarfBuzzSharp.HarfBuzzApi.hb_blob_create(Void* data, UInt32 length,
MemoryMode mode, Void* user_data, Void* destroy)
   at HarfBuzzSharp.Blob.Create(IntPtr data, Int32 length, MemoryMode mode,
ReleaseDelegate releaseProc)
   at HarfBuzzSharp.Blob..ctor(IntPtr data, Int32 length, MemoryMode mode,
ReleaseDelegate releaseDelegate)
   at SkiaSharp.HarfBuzz.BlobExtensions.ToHarfBuzzBlob(SKStreamAsset asset)
   at SkiaSharp.HarfBuzz.SKShaper..ctor(SKTypeface typeface)
   at SkiaSharp.HarfBuzz.CanvasExtensions.DrawShapedText(SKCanvas canvas,
String text, Single x, Single y, SKTextAlign textAlign, SKFont font, SKPaint
paint)
   at Jellyfin.Drawing.Skia.StripCollageBuilder.MeasureAndDrawText(SKCanvas
canvas, Single x, Single y, String text, SKPaint textPaint, SKFont textFont,
SKTextAlign alignment)
   at Jellyfin.Drawing.Skia.StripCollageBuilder.DrawText(SKCanvas canvas,
Single x, Single y, String text, SKPaint textPaint, SKFont textFont, Boolean
isRtl)
   at
Jellyfin.Drawing.Skia.StripCollageBuilder.BuildThumbCollageBitmap(IReadOnlyList`1
paths, Int32 width, Int32 height, String libraryName)
   at
Jellyfin.Drawing.Skia.StripCollageBuilder.BuildThumbCollage(IReadOnlyList`1
paths, String outputPath, Int32 width, Int32 height, String libraryName)
   at Jellyfin.Drawing.Skia.SkiaEncoder.CreateImageCollage(ImageCollageOptions
options, String libraryName)
   at Jellyfin.Drawing.ImageProcessor.CreateImageCollage(ImageCollageOptions
options, String libraryName)
   at
Emby.Server.Implementations.Images.BaseDynamicImageProvider`1.CreateCollage(BaseItem
primaryItem, IEnumerable`1 items, String outputPath, Int32 width, Int32 height)
   at
Emby.Server.Implementations.Images.BaseDynamicImageProvider`1.CreateThumbCollage(BaseItem
primaryItem, IEnumerable`1 items, String outputPath, Int32 width, Int32 height)
   at
Emby.Server.Implementations.Images.CollectionFolderImageProvider.CreateImage(BaseItem
item, IReadOnlyCollection`1 itemsWithImages, String outputPathWithoutExtension,
ImageType imageType, Int32 imageIndex)
   at
Emby.Server.Implementations.Images.BaseDynamicImageProvider`1.FetchToFileInternal(BaseItem
item, IReadOnlyList`1 itemsWithImages, ImageType imageType, CancellationToken
cancellationToken)
   at
Emby.Server.Implementations.Images.BaseDynamicImageProvider`1.FetchAsync(T
item, MetadataRefreshOptions options, CancellationToken cancellationToken)
   at
MediaBrowser.Providers.Manager.MetadataService`2.RunCustomProvider(ICustomMetadataProvider`1
provider, TItemType item, String logName, MetadataRefreshOptions options,
RefreshResult refreshResult, CancellationToken cancellationToken)
<<<

It seems the issue here is Skia is trying to use HarfBuzz to do the text
overlay, but lacks a .NET ("sharp") wrapper for HarfBuzz. (Apologies if I'm
butchering the terminology here, I'm not super familiar with .NET.) The
libSkiaSharp port provides such a wrapper for Skia, but there appears to be no
equivalent to the libSkiaSharp port for HarfBuzz. Some searching led me to:

https://github.com/SnapXL/freebsd-libskiasharp3/blob/main/Makefile

...where someone modified graphics/libskiasharp to also build a HarfBuzz .NET
wrapper. I tweaked this a bit to remove the jpeg-turbo part and just do the
libHarfBuzzSharp build, and that seems to have resolved my original issue:
Jellyfin is now able to generate the images with overlaid text as expected.
I've attached my final diff of the libSkiaSharp port not as a proposed patch,
but just to show how I resolved my issues. It may include some options that
aren't strictly needed.

Zooming back out, I wanted to put forward a few questions here. I know these
issues cross a couple different ports, so apologies for muddying the line
between them but hopefully it's okay since they're intertwined here and they
share the same maintainer:

1. Should Jellyfin declare a dependency on a font? My Jellyfin installation is
in a jail that only runs Jellyfin, so it is perhaps more stripped-down than
other people's and they happen to already have a usable font installed by
something else. But it does seem like not having any usable font installed
caused Jellyfin to error, so wanted to raise that.

2. Is my issue with missing libHarfBuzzSharp one that other people could
experience? I was a bit surprised to not find evidence of other folks
experiencing the same issue, so I wonder if this is somehow specific to me,
though I'm unable to imagine why that would be.

3. If my issue is relevant to others, should we try to fix that? And if so,
where? Adding libHarfBuzzSharp into the libSkiaSharp port like I did doesn't
feel right to me, given that they're separate pieces of software and the
non-.NET ports graphics/skia and print/harfbuzz are separate. So perhaps it
should be its own, new port? Or is it reasonable to assume that anyone who
needs libSkiaSharp would also need libHarfBuzzSharp, and thus makes sense to
include?

Sorry to bring such a half-baked solution here, it just took some effort to
find the solution so I wanted to start the conversation in case it can help
other folks avoid the same trouble. I'm hoping the maintainer's greater
expertise can help focus this into a smart path forward! Thank you for the
help.

-- 
You are receiving this mail because:
You are the assignee for the bug.