First contributors and a docs refresh

[b0bbywan]

First contributors, and the docs that explain why

Quick one to say thank you.

Huge thanks to @pbattino and @sm0kingm4n for being the first people outside of me to step into this project, and their feedback landed at exactly the right moment. @pbattino in particular is why the webradios integration has the shape it has. The discussion around it (#33) ended up being used as the worked example on the new Feature requests page, because it's the kind of loop odio is supposed to run on: a real use case, honest workarounds, a UX sketch, and back and forth until it feels like part of the system. New version with webradio support will land soon, before next week beginning I hope.

Also, if either of you would prefer not to appear by name on the docs site, just say the word and I'll take the mentions out. The docs are public and indexed, so it's a fair thing to opt out of.

On the docs side, two new community pages landed alongside a round of screenshots:

• Empowerment. This is where I finally tried to put into words why odio exists, and why the whole thing is built to be opened, broken, and rebuilt rather than treated as an appliance. If the tagline has ever felt vague, that's the page. And hopefully it gives you (and anyone else reading) a reason to keep contributing.
• Feature requests. A practical guide on how to propose something and what helps it move forward.

And a personal note on the docs themselves. I think they're one of the most important part of this project, and they're the easiest place to contribute. If a sentence tripped you up on a page, it'll trip the next person too, and fixing it is a real contribution with your name on the PR. No build pipeline to learn, just markdown in the docs repo. Honestly, good docs are the best marketing odio has, because they're what lets someone land here, get something running, and then have somewhere to go when they want to push further.

Three months of building this mostly solo (with an AI as sparring partner) has been a lot, and I'm still learning the community side of it. So, genuinely, thanks for being here.

Cheers.

[b0bbywan]

Activity page also, pretty nice, thx Claude https://docs.odio.love/community/activity/

Fun fact, this issue is part of what woke odio up. The contributor behind it is also the first one to have given an odio project a star on GitHub, before me even, before that name also. I'd never advertised that software, I was really pleased to see it could fit someone else's needs, and it kind of validated my fears: it's hard to set up. I know, I've been through it, maybe the docs aren't good enough in that repo. The R&D behind it was quite hard, not much fun. I tried to write that software first in bash 🤢 then Python 😒 and ended up trying my favorite language, Go 😃. That was bold, it was my first real programming dive into Linux user session subsystems and CGO, but it worked ok-tier, with ChatGPT sometimes to help.

When the issue opened, I noticed I couldn't understand some parts of the code anymore. What seemed to be a good pattern before had become unreadable, so I'd heard about Claude and asked him how we could fix that. That was a great talk 😃

Then go-odio-api appeared to push the Claude POC further. I had noticed KDE Connect, it seemed like a great idea, just not executed for my use case. They need a real graphical environment, and a complex auth system, C or C++ I think, definitely not something I'd be able to contribute to in order to fix my needs. There was some serious R&D behind go-odio-api and I loved it. It shows in the 30% of closed PR in that project. I loved really discovering more about the Linux user session, and even though I started by hating systemd, like everyone, I now really love it. Except systemd-resolved, I hate you. The hardest part was definitely testing on my PC and assuming it worked fine, then discovering the Raspberry Pi B+ couldn't handle it. Dealing with this was really the hardest part. I tried to solve it with design, rather than micro code optimizations.

I broke odio-api's config and introduced some security risks very early in the process, so I invested early in tests for the core logic and internal APIs too. Not much in the low-level backend though, it's not worth spending time on compared to real-life testing. Config, backend lifecycle, security, and API are covered as much as possible by CI. The security risks were fixed with a design solution: only expose what is required by the configuration, nothing more, and never expose root commands. That's an ok contract in my opinion. The default binary config is perfectly safe.

I was super excited about this API, and nobody around me cared because nobody seemed to understand what you could do with it, even with a Home Assistant integration 🤔

So I added the UI dashboard. Loved the HTMX/Tailwind embedded solution. I think the dashboard is a real success UX-wise. If you think otherwise or have improvement ideas, feel free to open a discussion. It was also a game changer for debugging the API and underlying backends. 🧐

Not much more understanding from people around me, even when I finally landed the Bluetooth backend, definitely one of the biggest challenges I faced, both technically and UX-wise 😮

The PWA: my relatives finally understood something! "That's an app!" 😅 The part where there's no store did impress a few.
On that note, I load the UI in an iframe and don't really use SSE except for node availability. I'm actually surprised it works so well. That it even works at all, even. The mixed content between HTTPS PWA and HTTP API/UI only throws a warning, I really expected an error. If someone has an explanation, please tell me. Svelte looks like a good framework for a non-frontend guy like me (and Claude of course).

Then I added SSE to the API, because I noticed my Home Assistant integration was making the whole system lag, and flat bug 😱.
First time I developed an SSE endpoint, really nice tech, DX is neat, both on server and client side.

Almost completely rewrote the first version of the integration which was really vibecoded, with better Python and HA integration standards. The integration currently has 99% test coverage, and supposedly Silver quality Integration Standard 🤓
This time I had also spent more time in the HA integration developer docs to make sure what I was doing with Claude was OK, especially regarding entity management and best practices.

Big breakthrough scrolling Reddit(https://www.reddit.com/r/raspberry_pi/comments/1rluwc7/comment/o8y41cd/?context=3) when I finally found a way to cross-build go-mpd-discplayer with its CGO dependencies in CI. It really helped for the next phase. I could finally distributes all my packages on odio-apt-repo

I also ended up adding a spotifyd fork on that apt repo, with fixed arm builds. I've opened a PR to try and merge that in the real repository, but no sign for now

With this covered, I started working on the streamer installer. With that stack ready, I had a real proposal for a go-odio-api use case. So that my relatives can finally understand what I've been working on with so much passion 😃

The hard part was'nt software configuration, as I had already done that years ago, and I had already prepared a lot of stuff on this fork of Raspberry Pi OS. I never really finished it, because I wasn't really happy with that solution: it would have been harder to port to x86_64 or live install. Also I've worked with Ansible for more than 10 years, so having Claude convert the fork to an Ansible role was pretty easy, except for the configuration part (live/image mode split for example). The bash scripts that manage both test and install were quite a piece of cake too.

But the real hard part is testing everything. The CI and my tests should ensure the complete installer always works, but you never really know until you ship it. And since I've decided to go blind on exploitation, real feedback is my only way to know what works and what doesn't. Especially UX-wise. It's kind of hard for me to go blind. I do it for the freedom promise, but that's really not something I'd normally do. At some point, I'd like to add some light opt-in anonymous telemetry, but that's far away.

Then I finally found the courage to plug a USB drive into odio. Turns out testing and fixing udisks MPD mounting in headless wasn't much work after all. My previous R&D Pi install was a precious appliance I was afraid to break, so I had never really tested that specific mode. With odio I finally could.

Final tests and system design improvements, before working on the Raspberry Pi Imager version. That was hard to do, and especially to design, since it was supposed to be about onboarding: it has to be obvious, flawless. And tested a lot. That's the commit breakdown on W13 I think. Loads of commits, rebased, squashed and fixed up before merging.

The 1st issue mentioned again motivated me, to serve the local cover (file://) over HTTP, as it seemed to improve UX. Since polling that endpoint on the UI was hurting the Pi, I finally switched the UI to SSE. It feels way smoother now, great improvement. Also created a fork of mpDris2 so I could really serve local CD covers over MPRIS and the UI. That's what the issue is about 😉

Really not sure what got me working on the docs. At first it was mostly Claude rewrite of my medium articles in a more actionnable way. Then I figured real use cases might be the key for onboarding. I think it worked ? I've got various feedback of people wanting to do something, and finding an easy workaround by themselves. This early in a whole new streamer project, I consider this a design and UX validation 🥰 I really use those to feed the docs. If it's really useful, it's the best SEO possible. And it'll really help ship a nice release out of the beta period. I've got no idea when to end it btw. I "can't" merge odio.love and get stats about it until I do, bad design part on my end I think 🙄

And now my relatives finally understand ! ♥️ Some part at least 😅

go-odio-notify appeared. It's really a PoC at this point, an improved version by Claude of the notification system extracted from go-mpd-discplayer, notifications backend, see #42 might be a great way to get involved too.

Sorry for the wall of text. I felt like doing a retrospective and didn't really know where to post it, so here we go. I hope you'll appreciate the read and that it gives some insights into how I work. It resonates a lot with https://docs.odio.love/community/empowerment/. I never thought I'd be capable of building something like this before actually trying. After years of tinkering and watching what others were doing, I decided to put my own proposal out there and design it so others have a platform to also hack and learn as much as I did while working on odio. ♥️