UltraScrapSharp

A .NET 10 implementation of UltraStar-CLI for searching the USDB catalog and downloading complete, ready-to-sing UltraStar song folders.

This repository is a C# port of the original project by martiinii/UltraStar-CLI. Thank you to the original author for creating and sharing the application that inspired this work.

Overview

UltraScrap is designed to make building an UltraStar song library simple and reliable. Search by artist or title, review results, and download a complete song folder with the files you expect for playback and singing.

The solution includes three projects:

• UltraScrap — Terminal.Gui-based CLI/TUI application
• UltraScrap.Web — Blazor Server web application
• UltraScrap.Core — shared services for search, session management, downloads, and storage

Features

• Search the USDB catalog by artist and title
• Download complete song folders with song.txt, video.mp4, and optional cover.jpg
• Use either a desktop-friendly terminal UI or a browser-based Blazor interface
• Automatically create and reuse an anonymous USDB account on first run
• Store configuration and library metadata locally
• Run on Windows, macOS, and Linux with .NET 10

Screenshots

CLI

Search	Library	Settings

Web

Search	Library

Downloads	Admin

Requirements

Install the following before running UltraScrap:

• .NET 10 SDK
• yt-dlp available on your PATH

Install .NET 10

• Windows: winget install Microsoft.DotNet.SDK.10
• macOS: brew install dotnet
• Linux: install the .NET 10 SDK from your package manager or Microsoft

Install yt-dlp

• Windows: winget install yt-dlp.yt-dlp
• macOS: brew install yt-dlp
• Linux: install yt-dlp from your package manager

For additional installation options, see https://github.com/yt-dlp/yt-dlp#installation.

Get the Latest Version

Anyone can clone this repository, pull the latest changes, and run the current version locally.

Clone the repository

git clone https://github.com/cvizzini/UltraScrapSharp.git
cd UltraScrapSharp

Update an existing checkout

git pull

Build and Run

Build the full solution

From the repository root:

dotnet restore UltraScrap.sln
dotnet build UltraScrap.sln -c Release

Run the CLI

cd UltraScrap
dotnet run -c Release

Run the web app

cd UltraScrap.Web
dotnet run -c Release

Then open the URL shown in the console.

Windows Quick Start

For Windows users, the repository includes helper scripts:

• build.bat — pulls the latest changes, restores, builds, and runs the CLI
• UltraScrap.Web\build.bat — pulls the latest changes, restores, builds, and runs the web application

These scripts are intended to make updating and running the project straightforward for anyone using a local Git checkout.

Publish the CLI as a Self-Contained App

cd UltraScrap
dotnet publish -c Release -r win-x64 --self-contained

You can replace win-x64 with another runtime identifier such as linux-x64 or osx-x64.

How It Works

UltraScrap searches the USDB website, manages its authenticated session, and assembles a complete local song folder by combining:

• song metadata and lyrics from USDB
• video downloads through yt-dlp
• cover artwork when available

Downloads are first staged and only moved into the final library when the required files are present.

Repository Layout

.
├── UltraScrap.sln
├── UltraScrap.Core/   Shared services, API integrations, storage, and orchestration
├── UltraScrap/        Terminal.Gui host
├── UltraScrap.Web/    Blazor Server host
└── Images/            Documentation screenshots

Notes

• On first run, the app creates and stores an anonymous USDB account automatically.
• If no library path is configured, UltraScrap falls back to a local songs folder.
• The web application uses an admin PIN only for the /admin section.

Acknowledgements

This project is a respectful port of the original UltraStar-CLI. Sincere thanks to martiinii for the original concept and implementation.

License

MIT. See the repository license for details.