Forem: Kumneger0

Listen to Spotify in Your Terminal Without Premium Subscription

Kumneger0 — Sun, 18 Jan 2026 10:36:24 +0000

Hey, folks, recently, I made a project called Clispot, and in this blog post, I’ll try to explain about it, like what it is, why I built it, and how it works. Clispot is a CLI app that lets you listen to Spotify songs right from your terminal. You can listen to your favorite playlist, tracks, and more.

Why

I was so tired of using Spotify from GUI; it takes more than 1 GB of RAM, and I want something simpler and a lightweight option. So I tried searching for already built solutions, and I found spotify-tui and ncspot. When I saw them, I was happy and I said to myself, "Oh finally I don’t have to use Spotify from GUI anymore!" So I downloaded the app and tried to use it, but it didn’t work. I went back to the GitHub page to see if there was anything I was missing, and I found the issue: both of them require you to have a Spotify Premium account. I tried to investigate why both of them require a Spotify Premium account, and it turns out it is a limitation from the Spotify API. So I decided to build it for myself, something that works for a free account.

How does it work

So, if the restriction is from Spotify itself, I need to find a workaround to achieve this. I then found a project called spotDL, which is a Spotify downloader. When you download a track using spotDL, it finds the matching song on YouTube using music metadata from Spotify

When I knew this, I wanted to do the same, but instead of downloading the whole audio file before starting to play, I wanted to stream directly from YouTube. I did some experiments to see if I could do that. You know what, it did work, but we need to have three dependencies: yt-dlp, ffmpeg, and oto, which is a golang audio library that allows us to play the track. We need yt-dlp to stream the audio from YouTube, and we need ffmpeg for audio conversion. The audio library we are about to use for playing the track doesn’t support playing the audio that comes from YouTube, so we need to convert to RAW PCM, which is supported by the audio library

Here is a visual diagram of how this works

First, request Spotify to get music metadata, like track name, artist name, album, etc, then search for that song on YouTube using yt-dlp. This code searches for the song, takes the first result, and streams directly to stdout

  searchQuery := "ytsearch:" + trackName + artistName

  args := []string{
        searchQuery,
        "--no-playlist", 
        "-f", "bestaudio",
        "-o", "-", 
    }

    cmd := exec.Command("yt-dlp", args...)

        _ = cmd.Start()

We have managed to search and stream video, so what is next? Next up, what we're gonna do is read the child process’s stdout, that is, where the streams are saved, and convert it to RAW PCM on the fly

ff := exec.Command("ffmpeg",
        "-i", "pipe:0", 
        "-f", "s16le", 
        "-ac", "2",   
        "-ar", "44100", 
        "pipe:1", 
    )

 ff.Stdin = ytOut 

    pr, pw := io.Pipe()
    ff.Stdout = pw 

    ctx, ready, _ := oto.NewContext(&oto.NewContextOptions{
        SampleRate:   44100,
        ChannelCount: 2,
        Format:       oto.FormatSignedInt16LE,
    })

    <-ready 
    player := ctx.NewPlayer(pr) 
    player.Play()

The FFmpeg command looks scary at first. I didn’t know any of those flags before working on this either.

The above code takes the output of yt-dlp and converts it to raw PCM, then we pipe the output of ffmpeg to oto using io.Pipe And then oto plays it on the fly

Let’s put it all together

package youtube

import (
    "io"
    "os/exec"

    "github.com/ebitengine/oto/v3"
)

func SpotifyYoutubeStreamer(artistName, trackName string) {
    searchQuery := "ytsearch:" + trackName + artistName

    args := []string{
        searchQuery,
        "--no-playlist",
        "-f", "bestaudio",
        "-o", "-",
    }

    cmd := exec.Command("yt-dlp", args...)

    ytOut, _ := cmd.StdoutPipe()

    _ = cmd.Start()

    ff := exec.Command("ffmpeg",
        "-i", "pipe:0",
        "-f", "s16le",
        "-ac", "2",
        "-ar", "44100",
        "pipe:1",
    )

    ff.Stdin = ytOut

    pr, pw := io.Pipe()
    ff.Stdout = pw

    ctx, ready, _ := oto.NewContext(&oto.NewContextOptions{
        SampleRate:   44100,
        ChannelCount: 2,
        Format:       oto.FormatSignedInt16LE,
    })

    <-ready // waiting for hardware audio devices to be ready you can read more about it on the oto docs
    player := ctx.NewPlayer(pr)
    player.Play()

}

The actual code on clispot may be a bit different. This simplified version for clarity

That is how Clispot works

Headless mode

We have a feature called headless mode, which provides an HTTP interface without the TUI, so anyone can build any other client application on top of Clispot, like web apps. That is how our VSCode extension is built. This feature is specifically added for our VSCode extension

When you use our VS Code extension, it runs clispot --headless behind the scenes for you

In this mode, the audio playback is handled by clispot, not by the extension; the extension is responsible for fetching your libraries, allowing you to manage your music queue, and allowing you to search for any music you want

Limitations

Even though this setup works fine, it has some limitations. The first one is yt-dlp, which has slow download speed, and a lot of yt-dlp users are experiencing this issue, and the second one, YouTube, sometimes says Sign in to confirm you’re not a bot

In this kind of scenario, yt-dlp fails to download the audio. Luckily, yt-dlp provides an option to pass browser cookies so it can bypass this restriction. To do that in Clispot, you can use clispot --cookies-from-browser <browser name>

clispot --cookies-from-browser brave

If you run this, clispot will pass this flag directly to yt-dlp, so it’ll use the cookies from Brave

Check out their docs to see supported browsers

Conclusion

I hope you enjoyed this article. The project is open source; you can see the source code in this repository. Let me know what you think about this post in the comments below. If you have any questions, feel free to ask me on Twitter.

Ensuring Type Safety in Next.js Routing

Kumneger0 — Sat, 20 Apr 2024 12:32:00 +0000

Last week, I explored an open-source project called declarative routing. This project facilitates the implementation of a type-safe routing system within Next.js applications. I'm interested in writing a short article about it and the insights I gained from building a small project that utilized declarative routing.

What Is Declarative-Routing?

While type-safe routing offers many benefits, it can introduce challenges when working with URLs. Consider the following example:

<Link to={/post/${post.id}}>post</Link>

This approach might lead to issues if the URL structure or parameters change later.

Declarative routing offers a solution by providing components specifically typed into routes. These components handle URL construction automatically. For instance, with a component named PostDetail.Link, you could write the code as

 <PostDetail.Link id={post.id}>post</PostDetail.Link>

This approach ensures that any updates to the route or its parameters are reflected consistently throughout your application, wherever the PostDetail.Link component is used.

Build a Small Next.js App with Declarative Routing

The source code for this project is publicly available on GitHub
to get started with Declarative Routing: run the following command:

npx declarative-routing init

This will create a directory called @/routes, which you can use to access websites and submit API queries. In the routes directory, it also creates a README.md file with instructions on how to utilize the system.

**To keep the @/routes directory synchronized with your application's routes, be sure to run the following command whenever you modify existing files or introduce new routes:

npx declarative-routing build

This will generate info.ts files in the same directory as page.tsx or route.ts Subsequently, it will import these .info.ts files into @/routes/index.ts, allowing you to import all the routes from @/routes and utilize them within your application

The project appears to have three routes:

Home (/): leads to a list of posts.
PostID (/posts/): Enables viewing individual posts.

Additionally, there is one API endpoint located at src/app/api/posts/route.ts, which is used to retrieve lists of posts. The posts being used are located at src/db/db.ts, which exports an array of dummy data. We are sending that data from our API route.

Home

here is the code for the homepage

"use client";
import EachPost from "@/components/posts";
import { getApiPosts } from "@/routes";

import React, { useEffect, useState } from "react";

function Post() {
  const [posts, setPosts] = useState<Awaited<ReturnType<typeof getApiPosts>>>(
    []
  );

  const [limit, setLimit] = useState<number | null>(null);

  useEffect(() => {
    getApiPosts({}, { limit }).then(setPosts);
  }, [limit]);

  return (
    <div>
      <div>
        <h1 className="font-bold text-2xl ">API Route Example</h1>
      </div>
      <div>
        <input
          type="number"
          placeholder="Add limit"
          className="p-3 rounded-xl border border-black"
          onChange={(e) => setLimit(Number(e.target.value))}
        />
      </div>
      <div>
        {posts?.map(({ id, title }) => (
          <EachPost id={Number(id)} title={title} key={id} />
        ))}
      </div>
    </div>
  );
}

export default Post;

Let me explain the code above. We import getApiPosts from "@/routes," which is auto-generated by calling declarative-routing build. This function retrieves a list of posts from /api/posts and updates the state variable.

At this time, you may be wondering why not simply use a server component and invoke getApiPosts at the top level of the component? Well, you are right, but there is an issue.

if you do that, you will get an error Failed to parse URL /api/posts

When calling getApiPosts, we are simply making a fetch call to /api/posts.

In server components, you need to specify an absolute URL. In a web browser, when you say fetch('/api/posts'), the browser assumes that it's relative to the document base URL/origin.

For more information, check out this issue.

How Does getApiPosts function work?

if you see @routes/index.ts below

// Automatically generated by declarative-routing; do NOT edit
import { z } from "zod";
import { makeGetRoute, makeRoute } from "./makeRoute";

const defaultInfo = {
  search: z.object({})
};

import * as HomeRoute from "@/app/page.info";
import * as ApiPostsRoute from "@/app/api/posts/route.info";
import * as PostsPostIDRoute from "@/app/posts/[postID]/page.info";

export const Home = makeRoute(
  "/",
  {
    ...defaultInfo,
    ...HomeRoute.Route
  }
);
export const PostsPostID = makeRoute(
  "/posts/[postID]",
  {
    ...defaultInfo,
    ...PostsPostIDRoute.Route
  }
);

export const getApiPosts = makeGetRoute(
  "/api/posts",
  {
    ...defaultInfo,
    ...ApiPostsRoute.Route
  },
  ApiPostsRoute.GET
);

The makeGetRoute function is a helper function that generates these type-safe get functions. It takes three arguments:

The path for which the function should be generated. In the case of getApiPosts, this would be "/api/posts.".
An object that contains the schema for the route's parameters and query parameters. This is typically generated from a.info.ts file that is associated with the route.
An optional object that represents the schema for the response data expected from the endpoint. This ensures that the data returned from the endpoint adheres to the expected structure, further enhancing the type safety of your application.

Creation of page routes with Declarative Routing

makeRoute: This function is used to define a page route. It takes the path of the route as a string and an info object that contains the name of the route, as well as the Zod schemas for the route parameters and search parameters. This function ensures that any access to the specified route adheres to the expected structure, enhancing the type safety of your application. Here is an example usage:

export const Home = makeRoute(
  "/",
  {
    ...defaultInfo,
    ...HomeRoute.Route
  }
);

In the example above, Home is a type-safe function that constructs the URL for the home page. It ensures that any access to the home page route adheres to the expected structure, further enhancing the type safety of your application.

Creation of API routes with Declarative Routing

In declarative routing, API routes are defined using makeGetRoute, makePostRoute, makePutRoute, and makeDeleteRoute functions. These functions facilitate the creation of type-safe functions for API endpoints in your Next.js application.

makePostRoute: This function is used to create a type-safe function for POST requests to an API endpoint. It takes the path of the route as a string, an info object that contains the name of the route, and Zod schemas for the route parameters and search parameters. It also takes a secondary object containing the body schema. The function ensures that any POST request to the specified route adheres to the expected type structure, enhancing the type safety of your application.
makePutRoute: Similar to makePostRoute, this function is used to create a type-safe function for PUT requests to an API endpoint. It takes the same arguments as makePostRoute, including the path, info object, and body schema. The use of this function ensures consistency and type safety when making PUT requests in your application.
makeDeleteRoute: This function is used for DELETE requests. It takes the path of the route as a string, an info object containing the name of the route, and the Zod schemas for the route parameters and search parameters. It does not require a body schema, as DELETE requests typically do not include a body.

The getApiPosts function accepts three parameters based on the following object located at src/app/api/route.info.ts:

export const Route = {
  name: "ApiPosts",
  params: z.object({}),
  search: z.object({ limit: z.number().nullable() }),
};

Parameters:

The first argument corresponds to the Route.params property, which is an empty object in this case.
The second argument aligns with the Route.search property. It accepts an optional limit parameter of type number. If you omit the limit parameter, an error will occur. Argument of type '{}' is not assignable to parameter of type '{ limit: number | null; }'.
The third argument (optional) allows you to pass additional options like headers and methods, similar to the options argument in the Fetch API

How Does getApiPosts function work?

if you see getApiPosts in @/routes/index.ts

After retrieving the posts from the server, we update the state variable. The posts are then displayed on the page, and the EachPost component handles rendering each post's title

import { PostsPostID } from "@/routes";
import React from "react";

function EachPost({ id, title }: { id: number; title: string }) {
  return (
    <div key={id}>
      <PostsPostID.Link postID={String(id)}>
        <div className="text-xl text-blue-700 hover:text-blue-500 hover:underline">
          title : {title}
        </div>
      </PostsPostID.Link>
    </div>
  );
}

export default EachPost;

The EachPost component accepts two properties: postId and title. It renders a link to /posts/<postId> using the PostsPostID.Link component. As previously mentioned, this component is auto-generated and functions similarly to the following code:

<Link href={`/posts/${id}`}>{title}</Link>

However, the advantage of using PostsPostID.Link is that it offers type safety. This means that if you forget to pass the postID or pass it in the wrong type, your code will not compile, thus preventing potential runtime errors. This is a significant benefit of declarative routing in Next.js applications.

The open-source project, declarative routing, provides a type-safe routing system within Next.js applications. It offers components specifically typed into routes, handles URL construction automatically, and ensures consistent updates throughout the application.

Thanks for reading! If you enjoyed this post and want to see more content like this, head over to my website I'd love to see you there!