Atrium — a native tvOS app for your Emby server

[vdatanet 1664]

Hi all,

I've been building Atrium, a native tvOS app for home media servers, and as of version 1.2 it
works with Emby. It's on the App Store, it's free, and it stays free: no in-app purchases, no
subscription, no ads, no tracking, and no Atrium account — you point it at your own server, sign in
with your own user, and that's it. (It speaks to Jellyfin servers too; the app doesn't ask you
which, it works it out when you connect.)

Some of you may remember me from topic 149003, where I asked about the HLS manifest a few weeks
ago. That thread is the reason this post has one caveat, and I'd rather lead with it than have
anyone find it on their TV.

--- With Emby, HDR video is tone-mapped to SDR ---

Here is why, as precisely as I can put it.

On Apple platforms the player decides the display mode from the multivariant playlist *before* it
downloads a single segment. It reads the attributes on #EXT-X-STREAM-INF — VIDEO-RANGE, CODECS —
to work out what the stream is and to configure the display. Emby's transcoding manifest currently
carries neither, so tvOS has nothing to act on and never switches the TV into HDR mode.

The bytes are fine, and I checked: I pulled the #EXT-X-MAP init segment and the first media
segment, concatenated them and ran ffprobe. It comes back smpte2084 (PQ) with BT.2020 primaries —
real HDR, being sent right now.

But an app can't use that. If it just plays the stream, the display stays in SDR, and PQ content
shown on an SDR display looks washed out — worse than not trying. So Atrium does the honest thing
instead: it tells the server it accepts SDR, the server tone-maps, and what you see is correct.
Less than the file holds, but right.

One thing that makes this cheaper than it sounds: the transcode currently comes out 8-bit
(yuv420p) even when the command line asks for main10, and PQ at 8 bits bands visibly. So what is
actually being given up is smaller than "no HDR" makes it sound.

--- What would change it ---

Populating VIDEO-RANGE and CODECS on #EXT-X-STREAM-INF (and SUPPLEMENTAL-CODECS where Dolby Vision
applies), reflecting what the stream really is. That's the whole ask — it isn't a change to what
the transcoder produces, only to how it's described.

On my side the HDR path is already written and shipping; asking for HDR again instead of SDR is a
one-line change and a release. I'd be glad to test any build against a 4K HDR/DV library and report
back with player-side measurements: which variant is chosen, what the player reports the range as,
and whether the display actually switches.

--- Everything else ---

Libraries, search, Continue Watching, the Apple TV top shelf, subtitles through the native tvOS
picker, music with a proper queue. If something doesn't work the way you expect, I'd genuinely
like to hear about it — this is the first release Emby users have had their hands on, and you'll
find things I can't.

https://apps.apple.com/app/atrium-media-player/id6777638751

Thanks — and thanks for the pointers in the earlier thread, they're what got the measurements
right.

Edited Tuesday at 11:24 AM by vdatanet

[alex77777 52]

@vdatanetSo just to clarify, currently your app only displays SDR at the moment? 

I'm testing it out and honestly its a really smooth experience. Do you plan on having it direct play formats like DTS-HD MA and TrueHD to the Apple TV similar to how Infuse does it?

[vdatanet 1664]

No — the app does HDR10, HLG and Dolby Vision, and against other server types it already switches an Apple TV 4K into HDR correctly. What you're seeing as SDR is Emby's side of the HLS path, and I've measured it fairly carefully.

Emby's #EXT-X-STREAM-INF carries no VIDEO-RANGE attribute and no CODECS attribute. On Apple platforms the player decides what a stream is before it downloads a single segment — it reads those attributes both to rule variants in or out and to pre-configure the display — so with neither present, Match Dynamic Range never fires and the TV stays in SDR. The segments themselves are fine: I pulled the #EXT-X-MAP init segment plus the first media segment and ran ffprobe, once on an HDR10 title and once on a Dolby Vision one, and both come back smpte2084 / bt2020. Emby is sending me HDR right now; it just doesn't say so in the manifest, and by the time the player has a segment in hand it's too late. Full write-up and measurements are in this thread. If those attributes get populated, HDR works here with no change on my side.

On the audio: no, and that's a deliberate limit rather than something waiting on the roadmap. The app is built on AVPlayer/AVFoundation only — no bundled software decoder. That's the whole bet: hardware decoding, Match Dynamic Range and Match Frame Rate, the system transport UI, tvOS's own subtitle rendering. The price is that I'm bound by what AVFoundation accepts, and it doesn't decode or bitstream TrueHD or DTS in any form. Infuse ships its own player engine, which is how it can bitstream those to a receiver; doing the same would mean giving up everything above, and I'd rather push the native player as far as it goes.

In practice that means AAC, AC-3, E-AC-3, ALAC, FLAC and LPCM direct play untouched — including Dolby Atmos when it's carried in E-AC-3 (JOC), which is the form the Apple TV supports natively anyway. A TrueHD or DTS-HD MA track gets transcoded server-side, audio only, with the video still copied: you lose the lossless track, and TrueHD Atmos comes down to a channel bed. Most 4K remuxes carry a DD+ or AC-3 compatibility track alongside the lossless one — picking that in the audio menu direct plays, and keeps Atmos if it's there.

Glad the rest feels smooth — thanks for putting it through its paces.

[vdatanet 1664]

A correction to my own post, and it goes in Emby's favour, so I'd rather put it up than leave it
standing.

I wrote that Emby was sending real HDR and simply not describing it in the manifest, and that the
transcode came out 8-bit with visible banding. Both of those are wrong. I re-ran the same
measurement today against the same Emby version, and what arrives is a proper tone-map to Rec. 709
— on the HDR10 title and on the Dolby Vision one alike. The manifest carries no HDR label because
there is no HDR to label. That is Emby doing the correct thing.

What I had actually caught was a fault on my own server: tone-mapping was failing there in a way
that left the HDR tags attached to a picture that was no longer HDR, and I read the tags rather than
the picture. The same Emby build handles it correctly now, so that was my machine and not the
server.

What doesn't change is the limitation I posted about. With Emby, Atrium still shows SDR, for the
same reason as before: the manifest doesn't describe the dynamic range, so tvOS never switches the
TV into HDR mode, and asking for HDR anyway would only mean HDR content on a display that stays in
SDR. Asking for SDR is the honest option, and it's what the app does.

For anyone who wants the actual measurements, that side of it belongs in the developer section — I'm
posting the details in topic 149003.

 

[kalg 5]

only thing is your app dont play .mkv files due to using native player and most rips are in mkv container good job on the app keeep up the good work 

[vdatanet 1664]

5 minutes ago, kalg said:

only thing is your app dont play .mkv files due to using native player and most rips are in mkv container good job on the app keeep up the good work 

Thanks — glad it's landing well.

On the MKV point, though: they do play. What the app doesn't do is *direct* play the MKV container,
because the native player can't open it — so the server repackages it into a stream the player can
take. That's a remux rather than a re-encode: the video is copied through, not compressed again, so
it's a lot cheaper on the server than a full transcode and the picture is untouched.

My own library is about 96% MKV and all of it plays this way, so if you've got a specific file that
won't start, that's not the design and I'd like to hear about it — tell me the codecs and I'll dig
in.

Staying on the native player is a deliberate trade. It's where the system track picker, the chapter
menu and the rest come from, and having the server do the container work is a cheap price for it.

[vdatanet 1664]

An update to this thread, and it's the one I most wanted to be able to post: as of version 1.3,
which is on the App Store now, HDR works with Emby.

When I announced the app here I led with a caveat — HDR was being tone-mapped to SDR, because the
player on Apple TV decides the display mode from the HLS manifest before it fetches a single
segment, and a transcoded stream doesn't describe its dynamic range. That caveat is gone. Not
because anything changed on your side: the app stopped asking the server to prepare the video at
all.

For HDR films that qualify, Atrium now reads the original file from your server and does the
container work on the device. It repackages the MKV into a stream the native player can take and
writes the manifest itself, so the player knows exactly what it is being handed and the TV switches
into HDR. Nothing is re-encoded: video and audio are copied through untouched, and metadata a
transcode would strip — HDR10+, for one — arrives intact. What you see is the original 10-bit
picture, not a conversion of it.

The part your server will notice: it isn't transcoding any more. On my own machine, a 4K feature
that used to mean four minutes of ffmpeg and a warm box now shows no ffmpeg in the log at all —
just range requests for the file, which is the cheapest thing a server can do.

What qualifies, so nobody goes hunting for something that isn't there:

- HEVC video, HDR, in an MKV.
- At least one AAC, AC-3 or E-AC-3 audio track — those are the ones the app can copy.

Anything else keeps going through the server exactly as it did before, and so does everything that
isn't HDR. There is nothing to configure and nothing to turn on: if a film qualifies, that's the
path it takes.

This also finishes a point kalg raised earlier in the thread. MKVs always played — the server was
repackaging them — and for these films the app now does that part itself.

One thing that hasn't changed: the request I made over in topic 149003, for VIDEO-RANGE and CODECS
on the transcoding manifest, still stands and I still think it's worth doing. It matters for every
client that doesn't carry its own demuxer, which is nearly all of them, and for everything that has
to be transcoded anyway. The measurements are in that thread rather than this one.

1.3 also makes Resume the first button on a film's page, refreshes the page when you open it, and
hands audio track selection to the system picker where it can. As ever: if HDR doesn't light up on
a film you think should qualify, I'd like to hear about it — tell me the codecs and the container
and I'll dig in.

https://apps.apple.com/app/id6777638751

[jasonmcroy 326]

I just installed this tonight to play around with it. It looks really nice. Sleek and the playback is great. Works perfectly with my Homepods with none of that lagging audio when you restart or pause. So great job on this aspect!

I know this app is new, but wanted to check if you plan to implement using the Intro skip feature and end credits skip buttons for TV Shows? I use the credits detector plugin for credits. 

[vdatanet 1664]

44 minutes ago, jasonmcroy said:

I know this app is new, but wanted to check if you plan to implement using the Intro skip feature and end credits skip buttons for TV Shows? I use the credits detector plugin for credits. 

Thanks — and the HomePod part I can't take much credit for: Atrium plays through the native tvOS
player rather than bundling its own engine, so pausing, resuming and switching audio routes all go
through the same path the system apps use. Most of what feels right there is the platform.

Skipping intros is planned, yes — and your question sent me to look at my own server, where the
answer turned out to be sitting already. Intro detection is part of the server itself, and it writes
its markers straight into an episode's chapter list. Atrium already reads that list; it's what fills
the chapter menu in the player. So the data has been arriving in the app all along and I simply
wasn't looking at it. That's the half I'm comfortable saying yes to, because it works for anyone who
switches the detection on, with nothing else to install.

End credits I'd rather not promise. There seem to be several plugins that do it, each in its own
way, and a button built around whichever one I happened to install would quietly not exist for
everybody running a different one. What the server can do on its own is the line I'd like to stay
on.

But I would like to know what you use, and what it leaves behind on an episode once it has found
the credits — a marker, a chapter, something else? If there's a shape that's common to more than one
of them, that changes the picture, and it's the sort of thing I'd want to weigh up properly later
rather than guess at now.

No date on either of these, and preview thumbnails while scrubbing are still ahead of them in the
queue.

[Kyouma 37]

3 hours ago, vdatanet said:

Intro detection is part of the server itself, and it writes its markers straight into an episode's chapter list.

FYI it doesn't matter if it's in the chapter list of the episode itself. It's important if it's in Emby's DB.

I for example do not have any Intro/Credits chapters in the chapter list of my episodes, it's only in the DB. And I push them from an external application, so it shouldn't matter which one you use.

They all should be doing the same thing: creating markers in the DB.

[vdatanet 1664]

50 minutes ago, Kyouma said:

FYI it doesn't matter if it's in the chapter list of the episode itself. It's important if it's in Emby's DB.

I for example do not have any Intro/Credits chapters in the chapter list of my episodes, it's only in the DB. And I push them from an external application, so it shouldn't matter which one you use.

They all should be doing the same thing: creating markers in the DB.

That's a useful distinction, and it's exactly the shape I was asking about — thanks.

For what it's worth, that's already how the app reads it. It doesn't look at a file's own chapters:
it reads what the server hands back for the episode and goes by the marker type rather than the
name, since the names come through localised and matching on those would only ever have worked in
one language. So whatever put the markers there — the server itself, a plugin, your external tool —
makes no difference at this end.

Which is what makes your point the interesting one. My hesitation about credits was that every tool
would leave behind something of its own shape; if they all land in the same place with a type on
them, that's a different question.

The piece I'd still want before saying yes to it is the value itself: on your episodes, what does a
credits marker come through as, and is it a single start or a pair? Intros arrive here as a start
and an end; credits I'd expect to have only a beginning, with the end being the end of the file —
but I'd rather see one real example than assume and build the wrong rule.

[Kyouma 37]

4 minutes ago, vdatanet said:

The piece I'd still want before saying yes to it is the value itself: on your episodes, what does a credits marker come through as, and is single start or a pair?

It is only a single start, because Emby only has IntroStart, IntroEnd and CreditsStart. Currently there is no CreditsEnd marker available, but i hope it will soon come.

 

 

 

[vdatanet 1664]

1 hour ago, Kyouma said:

t is only a single start, because Emby only has IntroStart, IntroEnd and CreditsStart. Currently there is no CreditsEnd marker available, but i hope it will soon come.

That matches what I found — thanks for confirming it.

After your first message I went and read the two plugins myself, and they paint the picture you
describe: whatever it is that finds the timings, they all end up setting Emby's own marker type on a
chapter, so where the numbers come from really doesn't matter. One of them works around the missing
end by writing a plain chapter where the credits finish, which tells you how much people want that
marker to exist.

The detail that settled it for me was smaller, and a bit funny: on my server the intro markers come
through in Spanish and the credits one in English, because the server localises its own and a plugin
doesn't. A client matching on names would have got one of them wrong for sure. Reading the type is
the only thing that holds.

So I have a clear picture now, and the rest is the server's move: with only a start, a skip can
only ever land at the end of the file — which is exactly where anything after the credits lives. If
a CreditsEnd ever turns up, it arrives on the same path I'm already reading.

[Grumpy1 47]

sorry for the dumb question but cant figure out how to add manual server

 

what should it look like

[vdatanet 1664]

1 hour ago, Grumpy1 said:

sorry for the dumb question but cant figure out how to add manual server

Not a dumb question — the screen hides it, and on top of that there's something on my side that
means your server could never have shown up by itself. Here's where the button is, and what's
being fixed.

--- Where the button is ---

Open the app without a session and it spends a few seconds looking for servers on the local
network. Under that, there are two buttons side by side:

    [ ⟳ Search again ]    [ + Enter address manually ]

"Enter address manually" is the filled one on the right. You don't have to wait for the search to
finish — the button is there and selectable the whole time. It replaces the list with a single
field labelled SERVER ADDRESS and a Connect button. Type the address, press Connect, and the app
comes back with your server's name and version and the users your server publishes on its own
sign-in screen: pick yours, type your password, and you're in.

--- What to type ---

The same address you would type into a browser on that network:

    http://192.168.1.50:8096

  · 8096 is Emby's default HTTP port — 8920 if you've set up HTTPS. Include the port.
  · The http:// is optional; leave it out and the app adds it.
  · Don't use localhost or 127.0.0.1 — from the Apple TV, those mean the Apple TV.
  · A name works too (http://tower.local:8096), and so does a domain through a reverse proxy,
    including one where Emby lives under a subfolder.

If you don't know the address: open Emby in a browser on a computer on the same network and read
the address bar. If it says localhost, then it's that machine's own LAN address you need, and the
Emby dashboard will show it to you.

One thing you'll see in that field and should ignore: the example inside it currently reads
"servidor" instead of "server". That's a string I forgot to translate — not a hint about what to
type. It'll say http://192.168.1.50:8096 in the next build, which is what it should have said in
the first place.

--- Why your server wasn't in the list ---

This part is on me. The automatic search does broadcast on UDP port 7359, which is the right port —
but it doesn't send the message Emby answers to ("who is EmbyServer?"). So your server was never
actually asked, and no Emby server can appear in that list today. Nothing to switch on at your end,
and nothing wrong with your setup.

The next version asks the right question. Even then, manual entry stays and stays first-class:
broadcast doesn't survive everything — Docker bridge networking without 7359/udp published, guest
or IoT VLANs, access points with client isolation — so the address field is also getting the
example it should have had, and a shorter path to reach it.

Thanks for asking it out loud. This is the kind of thing that gets found by someone typing "dumb
question", and not by me.

[Grumpy1 47]

thanks for the very detailed answer

[jasonmcroy 326]

15 hours ago, vdatanet said:

Thanks — and the HomePod part I can't take much credit for: Atrium plays through the native tvOS
player rather than bundling its own engine, so pausing, resuming and switching audio routes all go
through the same path the system apps use. Most of what feels right there is the platform.

Skipping intros is planned, yes — and your question sent me to look at my own server, where the
answer turned out to be sitting already. Intro detection is part of the server itself, and it writes
its markers straight into an episode's chapter list. Atrium already reads that list; it's what fills
the chapter menu in the player. So the data has been arriving in the app all along and I simply
wasn't looking at it. That's the half I'm comfortable saying yes to, because it works for anyone who
switches the detection on, with nothing else to install.

End credits I'd rather not promise. There seem to be several plugins that do it, each in its own
way, and a button built around whichever one I happened to install would quietly not exist for
everybody running a different one. What the server can do on its own is the line I'd like to stay
on.

But I would like to know what you use, and what it leaves behind on an episode once it has found
the credits — a marker, a chapter, something else? If there's a shape that's common to more than one
of them, that changes the picture, and it's the sort of thing I'd want to weigh up properly later
rather than guess at now.

No date on either of these, and preview thumbnails while scrubbing are still ahead of them in the
queue.

Thanks for your response. Regarding the end credits, usually what happens in other apps is that Endcredits triggers Emby's built in "Next Episode" button. Currently, in the Emby app for example, if you didn't have end credits for a show, the next up button doesn't show until like the last 10 seconds. With the shows that do have end credits from the credit detector plugin, the next episode button just pops up when the show hits that time mark.

I did notice that in your app, shows with Intros flagged and end credits flagged, you show them under the timeline in the "Chapters" section already. So, your app does read them, if that helps at all.