Skip to content
BranchesTags

Repository files navigation

logo

SMoC

Steaming Music on Console

License .NET Status CI

A terminal-based music player (TUI) for streaming services, currently supporting Subsonic-compatible APIs and YouTube Music. Spotify, Apple Music, and other services are future features.

Features • Installation • Configuration and Setup • Usage

screenshot animated

Note

This project is not supported or endorsed by any streaming music service or major company. It is a hobby project and has no affiliation with Spotify, Apple, Google, or YouTube. The same warnings and disclaimers for the well-known yt-dlp project apply here.

🌟 Features

  • TUI Interface: Built with Terminal.Gui for a rich console experience.
  • Cross-Platform Audio: Powered by SoundFlow.
  • YouTube Music Integration: Powered by YouTubeMusicAPI. Search, stream, and manage your library.
  • Subsonic API Integration: Streaming client for any Subsonic-compatible server. For instance, Navidrome, Airsonic Advanced, Gonic, or Madsonic.
  • Visuals: Displays album art using Sixel graphics (requires a compatible terminal) and a beautiful real-time audio frequency spectrum visualizer.

Feature Progress

While most basic functionality is available and SMoC is totally usable, there's a lot left to do.

Feature Plan (Click to expand)
  • UI
    • Search Support
    • Command Bar
    • Song Table
    • Now Playing Bar
    • Album Art (Sixel)
    • Status Bar
    • Visualizations
    • Now Playing Screen
  • Playback
    • Play
    • Pause
    • Stop
    • Skip
    • Previous
    • Start Over
    • Repeat Track
    • Volume
    • Playback Device Selection
    • Gapless Playback
  • Queue
    • Add to End of Queue
    • Queue Next (after current song)
    • Remove
    • Advance to Next at End of Song
    • Repeat Queue
    • Shuffle
  • Search
    • Artist
    • Track
    • Playlist
    • URL
  • YouTube Music
    • Authentication
    • POToken
    • VisitorData
    • Metadata
    • Searching
    • Play Audio Stream
    • Album Art
    • Caching
    • History Tracking
    • Like
    • Dislike
  • Subsonic API-compatible Servers
    • Authentication
    • Metadata
    • Searching
    • Play Audio Stream
    • Album Art
    • Caching
    • History Tracking
    • Like
    • Dislike
  • Apple Music (gamdl as a reference)
    • Authentication
    • Play Audio Stream
    • Metadata
    • Searching
    • Play Audio Stream
    • Album Art
    • Caching
    • History Tracking
    • Like
    • Dislike
  • Spotify (librespot as a reference)
    • Authentication
    • Play Audio Stream
    • Metadata
    • Searching
    • Play Audio Stream
    • Album Art
    • Caching
    • History Tracking
    • Like
    • Dislike

🚀 Installation

Once installed some setup is required to use SMoC. See the Configuration and Setup section for more information.

Binary Release (Windows/Linux/MacOS)

Current release is v0.5.1.

Available for Windows x64, Linux x64, and MacOS ARM64.

Gentoo via Portage

SMoC is available via my overlay. To install, add my overlay and emerge it.

eselect repository add razza git https://github.com/mrazza/razza-overlay.git
emerge media-sound/smoc

Building from Source

# Clone the repository
git clone https://github.com/mrazza/smoc.git
cd smoc

# Build and run
dotnet run --project smoc/smoc.csproj

🎮 Usage

SMoC operates with a Vim-style command bar. Press : to enter command mode.

Navigation & Commands

Command Description
:a Switch to Artist mode
:a/<artist> Switch to Artist mode and search for <artist>
:t Switch to Track mode
:t/<track> Switch to Track mode and search for <track>
:p Switch to Playlist mode
:p/<playlist> Switch to Playlist mode and search for <playlist>
:likes Load your Liked Songs playlist
:url Switch to Playlist mode from URL
:url/<url> Load songs from a specific YouTube Music URL
:pq View the Playback Queue
:np View Now Playing screen
:np-vis Toggle real-time frequency visualizer in Now Playing
:v/<0-100> Set volume (e.g., :v/80)
:q Quit application

Playback Controls

Hotkey Action
Space Play / Pause
Ctrl+Space Stop
, (Comma) Previous Track (Restart if > 10s played)
. (Period) Next Track
[ Seek Backward 10s
] Seek Forward 10s
Up/Down/Left/Right Navigate Tables
h/j/k/l Navigate Tables (Vim style)
Shift + Nav Key Select multiple items
Tab Switch active pane
v / V (Shift+v) Toggle real-time frequency visualizer (on Now Playing screen)
Enter Open Song Context Menu for selected item

Song Context Menu

The Song Context Menu provides options for playback and queue management. It appears when pressing Enter while a song is selected in any song table.

Hotkey Action Details
p Play all from here Clears the playback queue and queues the track listing in its entirety. Then starts playback at the selected track.
o Play selection only Clears the playback queue and queues only the selected tracks. Then starts playback at the first selected track.
n Queue next Adds the selected tracks to the playback queue after the current track.
q Queue last Adds the selected tracks to the end of the playback queue.
Up/Down/j/k Navigate menu Moves the selection through the menu items.
Enter Execute selected action Executes the highlighted action and closes the menu.
Esc Close menu Dismisses the context menu without taking any action.

⚙️ Configuration and Setup

SMoC stores configuration and authentication data in ~/.config/smoc/ (on Linux).

Subsonic

To use a Subsonic-compatible service (like Navidrome, Gonic, or Airsonic):

  1. Ensure your server has the Subsonic API enabled.
  2. Configure your server hostname, port, scheme, username, and password under SubsonicConfig in config.json (see below).
  3. Set ActiveService to Subsonic under SmocConfiguration.

YouTube Music

To use YouTube Music:

  1. Set ActiveService to YouTubeMusic under SmocConfiguration.
  2. Setup required settings for YouTube Music authentication (see below).

SoundCloud

To use SoundCloud:

  1. Set ActiveService to SoundCloud under SmocConfiguration.
  2. Configure ClientId and AuthToken under SoundCloudConfig in config.json.

Authentication

Note

You need a YouTube Music Premium subscription to play most content.

To access your YouTube Music account, you need to extract your cookies from YouTube Music (these steps are copied from YouTube.js):

  1. Open YouTube Music in your browser (Incognito recommended).
  2. Open Developer Tools (F12) -> Network tab.
  3. Find a POST request to music.youtube.com.
  4. Copy the value of the cookie request header.
  5. Save it to ~/.config/smoc/cookie.txt.

Tip

It is recommended to open an incognito window or separate browser profile when getting your cookie information to avoid other browser sessions from invalidating the tokens. Once cookies are retrieved, close the session without logging out.

More recently, additional tokens beyond just cookies are often needed. POToken and Visitor Data are required in the tokens.json file in the same directory as your cookie.txt.

Tip

Run smoc --gentokens after setting up the cookie to generate necessary PO Tokens and Visitor Data automatically.

Config File

Create or edit ~/.config/smoc/config.json to customize settings.

Example Configuration (Click to expand) 
{
  "SmocConfiguration": {
    "LogLevel": "Information",
    "ActiveService": "YouTubeMusic",
    "SongCacheSizeBytes": 536870912,
    "SongCacheMaxElements": 0,
    "AlbumCoverCacheSizeBytes": 104857600,
    "AlbumCoverCacheMaxElements": 0,
    "VisualizerFps": 24,
    "EnableLoudnessNormalization": true,
    "LoudnessNormalizationMode": "Full"
  },
  "SubsonicConfig": {
    "ServerScheme": "https",
    "ServerHost": "subsonic.example.com",
    "ServerPort": 443,
    "Username": "username",
    "Password": "password",
    "UseToken": true
  },
  "ListenHistoryConfig": {
    "Enabled": true,
    "MinimumPositionSeconds": 30,
    "MinimumFraction": 0.5
  },
  "SoundCloudConfig": {
    "ClientId": "your-client-id",
    "AuthToken": "your-auth-token"
  },
  "YouTubeMusicConfig": {
    "PlayerId": "your-player-id"
  }
}

Common Settings

Section Key Type Default Description
SmocConfiguration ActiveService StreamingService YouTubeMusic Active service (YouTubeMusic, Subsonic, SoundCloud)
SmocConfiguration LogLevel LogLevel Information Minimum log level (Trace, Debug, Information, Warning, Error, Critical, None)
SmocConfiguration SongCacheSizeBytes long 536870912 Max song cache size in bytes (0 = no limit, default 512MB)
SmocConfiguration SongCacheMaxElements int 0 Max songs to cache (0 = no limit)
SmocConfiguration AlbumCoverCacheSizeBytes long 104857600 Max album cover cache size in bytes (0 = no limit, default 100MB)
SmocConfiguration AlbumCoverCacheMaxElements int 0 Max album covers to cache (0 = no limit)
SmocConfiguration VisualizerFps int 24 Refresh rate for the audio frequency spectrum visualizer (FPS)
SmocConfiguration EnableLoudnessNormalization bool true Enable track loudness normalization
SmocConfiguration LoudnessNormalizationMode LoudnessNormalizationMode Full Loudness normalization mode (Full, AttenuateOnly)
SubsonicConfig ServerScheme string http Subsonic API URI scheme (http, https)
SubsonicConfig ServerHost string null Subsonic server hostname
SubsonicConfig ServerPort int 80 Subsonic server port
SubsonicConfig Username string null Subsonic username
SubsonicConfig Password string null Subsonic password
SubsonicConfig UseToken bool true Use token auth instead of password
ListenHistoryConfig Enabled bool true Enable listen history tracking
ListenHistoryConfig MinimumPositionSeconds int 30 Min seconds for 'listened' status
ListenHistoryConfig MinimumFraction double 0.5 Min fraction for 'listened' status
SoundCloudConfig ClientId string null SoundCloud client ID
SoundCloudConfig AuthToken string null SoundCloud authentication token
YouTubeMusicConfig PlayerId string null Custom YouTube Music player ID

🤝 Contributing

Contributions are welcome!

📄 License

Distributed under the Apache-2.0 License. See LICENSE for more information.

About

Steaming Music on Console: cross-platform TUI-based streaming music player

Topics

consolecross-platformmusicplayerstreamingsubsonicsubsonic-clientterminaltuiyoutube-music

Resources

Readme
Apache-2.0 license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Contributors

Languages