Using Playlet Completely Offline

[midwesternrodent]

This is an edge case involving the loading of playlet-lib and the now deprecated API so I didn't want to clutter the project page with an issue or documentation PR once I found the root cause. I honestly think I may be the only person who will ever encounter this, but this seemed like a good place to share my findings where it won't clutter things up, but people can find it if they want. Feel free to remove if you'd rather people not attempt things like this.

Why this is a problem for me

I am a weird breed that wants my Roku to not talk to anything on the internet, that's probably not too weird but I also want to have apps on the TV and not use a set top box. I paid for the silicon, I'm darn well using it!

Because of that, I have my Roku connected to the network but I block outbound internet except for api.rokutime.com because Roku doesn't use NTP or allow you set the time manually like a normal person, and https certs for jellyfin and invidious fail if the time is wrong - which it will be because every time you shut the TV down, Roku resets the time to the time of the software build for your TV.

The only things I have installed on my Roku are Jellyfin and Playlet, so I can watch my own media locally and proxy my requests to YouTube through my invidious server.

The problem

Months ago, Playlet started taking a very long time to load when I opened the app unless I re-enabled outbound internet for the Roku on my firewall. At first, I thought this was an issue with my invidious server, as proxied videos started failing on all my devices around that time as well, but the issue persisted after I fixed that problem tonight. As I was troubleshooting, I found out if I waited about 2 minutes, Playlet would go through to the home screen.

Watching the logs for my firewall, I noticed a lot of queries for a subdomain of github.com which were being blocked, I tried whitelisting this but it was a game of whack-a-mole as I realized this was just github's CDN confusing the reverse DNS lookup in OPNsense so that was a non-starter. (In hindsight, this issue likely wasn't started by any change in Playlet, but by a change to my network which affected how I whitelist github.com for my other iOT devices - which my Roku shares a network with.)

I then started looking into the project files to see if I could find any more information, which is when I remembered there is a web interface for playlet at port 8888, so I connected there and found on the settings page there are logs available, and they showed the following:

[APP] Loading Playlet lib from https://github.com/iBicha/playlet/releases/latest/download/playlet-lib.squashfs.pkg
[APP] Playlet lib failed to load from https://github.com/iBicha/playlet/releases/latest/download/playlet-lib.squashfs.pkg in 91094 ms
[APP] Loading Playlet lib from https://github.com/iBicha/playlet/releases/latest/download/playlet-lib.zip
[APP] Playlet lib failed to load from https://github.com/iBicha/playlet/releases/latest/download/playlet-lib.zip in 30018 ms
[APP] Loading Playlet lib from pkg:/lib/playlet-lib.zip
[APP] Playlet lib loaded from pkg:/lib/playlet-lib.zip in 3128 ms

So playlet is trying to load a library from this github. Perusing the docs (very well documented, btw) I found out there was nothing nefarious about this attempted download, it's just an easy way to update playlet's functionality without having to release a whole new app to the Roku store. But it IS a problem for ME so I've got to find out how to stop it reaching out to github since OPNsense doesn't support wildcard host entries in the firewall rules (well, not without some effort)

Solution

I'll spare you how long it took me to figure this out, but in the "Why separate between Playlet and Playlet-lib" section of the docs, I found this statement (emphasis mine)

Playlet/Docs/README.md
Enable forks. If for some reason someone wanted to use a fork of Playlet (for example, another folk had other features or bug fixes that this repo doesn't), they don't need to publish a complete new app. The url to load playlet is configurable, and can be changed through a simple web api. Allowing and enabling forks is what makes FOSS thrive.

All I've got to do is find that API, which didn't seem to have any documentation. So I searched "API" in the repo and found that the documentation was removed about 6 months ago, which is honestly fair. To give it a shot anyway, I searched that version 0.38.1 for that playlet-web-api.yml file and found it and I see there is an endpoint for /api/playlet-lib-urls. Querying this with curl "http://roku.internal:8888/api/playlet-lib-urls" gives me the following response:

{
  "loaded": {
    "link": "pkg:/lib/playlet-lib.zip",
    "type": "embedded-zip"
  },
  "saved": null
}

Looking at the old API docs, saved is the url it's supposed to reach out to on each boot. Mine is null, so from the logs I was seeing in playelet I can assume it'll reach out to github before falling back to the built in lib file. On a whim, I decide to see if I can just POST the same information that's already there to fix my problem:

curl -X POST "http://roku.internal:8888/api/playlet-lib-urls" -H "Content-Type: application/json" -d '[{"link":"pkg:/lib/playlet-lib.zip","type":"embedded-zip"}]'

That changes my GET request to:

{
  "loaded": {
    "link": "pkg:/lib/playlet-lib.zip",
    "type": "embedded-zip"
  },
  "saved": [
    {
      "link": "pkg:/lib/playlet-lib.zip",
      "type": "embedded-zip"
    }
  ]
}

Which looks right I suppose, so I restart Playlet and suddenly, it works! Everything loads instantly and when I check my logs I see this:

[APP] Loading Playlet lib from pkg:/lib/playlet-lib.zip
[APP] Playlet lib loaded from pkg:/lib/playlet-lib.zip in 3251 ms

This will work for now, at some point I will probably setup a clone of the project locally and just change my URL for that .zip so I can enable the auto updates, but this works to get me working.

tldr

Playlet has a 2 minute timeout if it can't connect to github to get the latest release of playlet-lib. This is by design to enable faster updates and not an issue with the project. If you're also in the weird edge-case of Roku having no internet connectivity while still using Playlet, you can fix this by forcing playlet to to load the built-in file by using the API:

curl -X POST "http://roku.internal:8888/api/playlet-lib-urls" -H "Content-Type: application/json" -d '[{"link":"pkg:/lib/playlet-lib.zip","type":"embedded-zip"}]'

As always, thanks for making such a great project!

[iBicha]

That was a fun read, thanks for sharing!

I paid for the silicon, I'm darn well using it!

I respect that!

Yeah you pretty much solved the problem the way I would have given your objective.

I have some context to share related to this; first around removing playlet-web-api.yml, I was slowly noticing that it was getting out of sync with actual implementation, and I didn't get a signal that anyone was using it, so I figured it's better to remove it than keep a wrong source of truth for this api.

The other thing is about setting a custom lib url: I wanted to make sure folks can load a different version if needed, but I was also afraid for someone to lock themselves into a version that doesn't work. The custom url can get cleared in two cases:

• When a custom url fails to load, it will load the default one on next run (code)
• You can also pass flag clearPlayletLibUrls=true when launching app with curl. From CHANGELOG.md:

• Added launch argument clearPlayletLibUrls
• If the dev menu is used to load a custom Playlet lib url, but the lib does not have a functionality to revert back, curl -d '' "http://$ROKU_DEV_TARGET:8060/launch/dev?clearPlayletLibUrls=true" can be used to remove the custom lib, and revert to using default.

This is in case the app doesn;t even let you boot, so the web server doesn't even turn on - in which case curl -X POST "http://roku.internal:8888/api/playlet-lib-urls" will not work.

Bear in mind that Playlet (or anything related to YouTube) breaks and breaks pretty often, so you might find yourself solving for auto-updates if Github releases doesn't work for you.

Finally, don't worry about cluttering the project page with an issue or documentation PR, if there's things you want to know about feel free to ask, I will try my best to address things.

Cheers