Sometimes the smallest changes can throw your whole project into chaos. For me, that moment came with SoundCloud.
I was using SoundCloud for music integration in my major project, VibeShift, and everything was running smoothly—until one day, an API update changed everything. SoundCloud was migrating to HLS (HTTP Live Streaming) for their music, and while progressive downloads (MP3s, WAVs, etc.) were fine before, the update broke them.
I found myself scrambling to get a working solution. Nine hours later, I had something semi-functional—but it wasn’t sustainable. Most solutions I found online were either outdated, confusing, overly bloated, or not maintained. I realized: I didn’t want to rely on someone else’s unstable library.
That’s when I started Oddysee, my own HLS audio player library.
Planning & Architecture: Week One
The first week was all about thinking long-term. I asked myself:
- Do I make this React-only?
- Should it eventually support Vue or Svelte?
- What dependencies do I actually need?
I landed on a core TypeScript package, framework-agnostic so anyone could build a wrapper for their preferred framework. Since I work with React, I started with a React hook version.
The planning phase was crucial. I wanted Oddysee to be something I could trust, maintain, and eventually let others contribute to—without being tied to my personal brand.
Building Phase: Weeks Two & Three
Implementing HLS was hard as hell. HLS.js is a huge low-level library with tons of configurations, and wrapping it in a clean, readable API was tricky.
Challenges included:
- Designing an intuitive, readable API
- Testing it in example projects and in VibeShift locally
- Dealing with edge cases I didn’t anticipate
At one point, I came across Verdaccio, which is a really cool way to test your npm packages locally, but that’s a story for another article.
Publishing Oddysee
After three weekends of deep work, it was time to publish. And then reality hit: naming and scoping an NPM package is way harder than it looks.
I thought I could just publish a scope and be done—but finding a unique name took hours. Eventually, I landed on Oddysee. Plus, every other variation I tried was already taken. And when that failed, I decided to make it unscoped.
I also made the conscious decision not to attach my full name to the project. Not out of fear—rather, but to allow Oddysee to live independently, and eventually let someone else maintain or contribute without friction.
Reflection & Next Steps
Now that Oddysee is live, I can honestly say I feel confident about its next phase: allowing contributions, improving long-term stability, and filling a gap that HLS libraries currently have for developers. Adding audio is already hard but with music and podcast providers moving over to HLS I want the adoption to be easier compared to what I went through.
What I learned:
- Outdated libraries are a risk—even if “everything works” for now.
- Planning for long-term maintainability pays off.
- Building a framework-agnostic core makes contributions easier.
- Naming and publishing can sometimes be harder than coding.
Oddysee might be a small solution, but it’s built to last—and I can’t wait to see how it grows.
itskarelleh
/
oddysee-hls-audio-player
An audio player library that supports HLS(HTTP Live Stream). Built with TypeScript and HLS.js
Oddysee - HLS Audio Player
A library API that wraps around HLS.js for a better developer experience. Because audio streaming shouldn't require a PhD in streaming protocols.
Background
I built this because I needed an audio player that supported HLS, but all the solutions I came across were either bloated or not maintained Then I discovered HLS.js. It saved me but it wasn't easy! The developer experience feels like you're configuring a spaceship when all you want to do is play some music. This library wraps all that complexity into a simple, audio-focused API that actually makes sense.
Packages
- oddysee-typescript - Core player library (framework-agnostic)
- oddysee-react - React hooks wrapper
Installation
Core (Vanilla JS, or any framework)
npm install oddysee-typescript
React Hook
npm install oddysee-react
Quick Start
Vanilla JavaScript
import { HLSAudioPlayer } from 'oddysee-typescript';
// Simple usage - because it should be this easy
const player = new…
Top comments (0)