Blog

Engineering notes

Why Nova is built the way it is. Three decisions that shaped the whole application, written out in full rather than summarised into marketing copy.

Engineering

Why Nova does not use AVPlayer for local files

Playback architecture

Every Mac developer reaches for AVFoundation first. It is well documented, it is maintained by Apple, and it hands you hardware-accelerated playback in about twenty lines of code. We chose not to use it, and that single decision is why Nova opens files that most other Mac players will not.

The problem is not quality, it is scope. AVFoundation understands the containers and codecs that Apple has decided to support. That list is sensible for content distributed through Apple's own channels, and far too short for the files people actually accumulate: an MKV from a Blu-ray remux carrying HEVC video and a DTS-HD track, an AVI from a decade ago, an MTS straight off a camcorder, a WebM with Opus audio. Handed any of those, a player built on AVFoundation shows you a greyed-out window and an unhelpful error.

So local playback in Nova runs on libmpv, the engine behind mpv, which brings the complete FFmpeg demuxer and decoder set with it. That one choice resolves a long list of requirements at once:

  • Containers and codecs stop being a feature list and become a non-issue
  • Hardware decoding still runs through VideoToolbox, so the efficiency advantage of the Apple silicon media engine is kept
  • Subtitles render through libass, which means styled ASS and SSA files look the way their author intended instead of being flattened into plain white text
  • Audio filtering — a genuine ten-band equaliser, loudness normalisation, channel balance — comes from a mature filter graph rather than something we would have had to write
  • Frame stepping, A-B looping, per-track delay and aspect, crop, zoom and rotation are all engine-level operations that are exact rather than approximated

The cost is that we own more of the stack. libmpv has to be bundled, configured and kept current, and its threading model has to be respected: decoding happens on its own threads and the Flutter layer only composites the resulting texture. Get that boundary wrong and you get a beautiful interface that drops frames.

There is exactly one place where AVFoundation is the right answer, and that is AirPlay. Apple exposes no public protocol for sending video to an AirPlay receiver yourself, so Nova uses the system route picker and an AVPlayer with external playback enabled. The interesting detail is where that player reads from: not the file on disk, but Nova's own local HTTP server. It is the same delivery path used for Chromecast and DLNA, which keeps one compatibility engine instead of three.


Engineering

The real reason casting fails, and what Nova does about it

Nova Cast+

“Casting doesn't work” is rarely a networking fault. The device is found, the connection is made, playback starts — and then there is no sound, or a black screen with audio, or it stops after four seconds. The cause is almost always the same: the television cannot decode one of the tracks inside the file, and nothing in the chain told you which one.

A 4K film from a Blu-ray is typically an MKV holding HEVC video, a DTS-HD or TrueHD audio track, and subtitles as ASS or as PGS bitmaps. A mid-range smart TV from 2021 will usually decode the HEVC video without complaint, have no idea what DTS-HD is, refuse the MKV container, and ignore both subtitle formats entirely. Four tracks, three failures, one useless error message.

The naive fix is to transcode everything. It works, and it is the wrong answer: re-encoding 4K video pins the CPU or the hardware encoder, drains a laptop battery in under an hour, and throws away picture quality to solve a problem that was never about the picture.

Nova asks a better question — what is the least I can change? Before playback starts it probes the file for container, codecs, profile, bit depth, HDR metadata and resolution, and asks the device what it supports. A Chromecast announces its model, a DLNA renderer returns a formal sink list, and AirPlay has a known profile. Those two descriptions go into a planner that returns the cheapest viable plan:

  1. Direct Play. Everything is supported, so serve the file's bytes with range support. No CPU cost at all, and seeking stays instant.
  2. Remux. The codecs are fine but the container is not. Repackage the existing streams without re-encoding them — near-zero CPU, identical quality.
  3. Audio-only transcode. The video is supported, the audio is not. Convert the audio to AAC and copy the video through untouched. The picture is still bit-for-bit original.
  4. Full transcode. Only when the video codec, resolution or HDR format is genuinely impossible for the device.

For the Blu-ray MKV above, the plan is: video copied, audio converted to AAC, subtitles converted or burned in, container remuxed to MP4. Picture quality untouched, CPU cost a few per cent, decision made before you noticed there was one.

The interface deliberately hides all of it. You see “Optimising for your TV…”, then “Ready ✓”. But the planner also returns machine-readable reasons, so “More details” can tell you precisely which track forced which decision — and so Nova AI can answer “why won't this play on my TV?” with a real explanation rather than a shrug.


Product

The honesty rule

How we decide what to advertise

Media player feature lists are notoriously dishonest. “Supports 4K” can mean the file opens and then stutters. “Chromecast support” can mean a button that finds your TV and fails. “AI subtitles” can mean a menu item behind a waiting list. The lists get longer, and they describe less and less.

Nova's architecture document contains one rule, written down before any of the interface existed: a format, codec or feature is only advertised once it works end to end.

In practice that has sharper consequences than it sounds. Interfaces are defined before implementations exist, which is ordinary engineering. The unusual part is that the user interface for a capability stays hidden until a working implementation is registered against it. The Cast button does not exist until a casting protocol is live. An AI feature does not appear in the panel until a provider can actually perform it. You will never find a control in Nova that opens an empty panel or an apology.

The same rule governs this website, which is why there is a roadmap page separating what works today from what is being built and what is merely planned. It would be easier to list the finished product and leave the timing vague. Instead: the playback core, the home screen, Continue Watching and the localisation architecture are available now. Casting, the FFmpeg layer, the library and Nova AI are in progress. True HDR output, system Picture in Picture and the iPhone release are planned.

Codec licensing gets the same treatment. DTS decoding is described as available “where licensing and the platform permit”, because the honest answer depends on terms that are not entirely ours to set, and claiming otherwise would be a promise we could be forced to break.

The bet is simple. A shorter list you can trust is worth more than a longer one you cannot — and when Nova does say it plays something, you should be able to stop wondering.