DEV Community: Ojalla

My First MCP Server: Semantic Code Search

Ojalla — Mon, 15 Sep 2025 01:08:55 +0000

How I built a Model Context Protocol server that lets AI agents search codebases semantically using Seroost

Why I Built This

I’ll be honest: I wasn’t a fan of “agentic coding” at first. The idea of letting AI agents run around my codebase sounded messy. That changed after I watched a NetworkChuck video on making MCP servers. It clicked — if agents could use my tools safely, I could actually make them useful.

That’s where Seroost comes in. I had already built Seroost, a semantic code search engine in Rust that indexes and searches documents using TF-IDF. It’s fast, snippet-aware, and handles large directories well.

The missing piece? Connecting it to AI agents. That’s where the Model Context Protocol (MCP) comes in.

The Problem with AI Agents Today

Working with AI assistants like Claude or GitHub Copilot on big projects often feels like this:

You ask about “authentication logic”
It says “show me your files”
You copy-paste a dozen files
It still misses context

Most AI agents either rely on keyword search (grep) or shallow semantic search. They don’t really “understand” the structure of your project.

Enter MCP + Seroost

MCP acts like a universal adapter for AI tools. Think of it as the USB port for AI: one standard protocol that lets any agent plug into external tools.

By turning Seroost into an MCP server, I gave AI agents the ability to search codebases semantically, return ranked results with snippets and line numbers, and work without constant manual uploads.

Building the MCP Server

I kept the setup lean, focusing on three tools:

Set Index Path → Tell Seroost which directory to target
Build Index → Run the indexing process
Search → Query the indexed code with semantic/fuzzy matching

The server wraps Seroost’s CLI with Node’s child_process.spawn, parses the JSON results, and exposes them over MCP.

server.tool("seroost_search", "Search codebase semantically", {
  query: z.string().describe("Search term or natural language description"),
}, async ({ query }) => {
  const content = await runSearch(query);
  return { content: [{ type: "text", text: JSON.stringify(content) }] };
});

Simple, but powerful.

What Changes for AI Agents

Before

AI: Show me your authentication files.  
Me: *uploads 15 files*  
AI: Maybe this is it... but I might be missing context.

After

AI: Let me search your project for authentication logic.  
→ seroost_search("user authentication functions")  

Results:  
- /src/auth/authenticate.js: function authenticateUser(credentials)  
- /src/middleware/auth.js: const verifyAuthToken = (token) => { ... }

No more blind guessing. The agent can scan the entire project, find the right files, and jump directly to relevant lines.

Why This Matters

Speed: No manual uploads, instant discovery
Scale: Works across thousands of files
Semantics: Finds patterns (“error handling middleware”) not just keywords
Composability: Works with any MCP-enabled agent, not just one platform

Setup

Install Seroost (cargo build --release)
Clone the MCP server and run npm install
Add it to your AI client config:

{
  "mcpServers": {
    "seroost-search": {
      "command": "node",
      "args": ["/path/to/search-mcp/build/index.js"]
    }
  }
}

Run seroost_set_index, then seroost_index, then search away.

What’s Next

This is just the start. MCP makes it possible to expose any tool to AI agents:

Query databases
Analyze logs
Deploy cloud resources
Run tests

I plan to keep expanding beyond code search — but for now, Seroost shows what’s possible when you give AI a real toolbelt.

Final Thoughts

Building this taught me a few things:

MCP is still new, but incredibly promising
Simple tools become powerful when standardized
Semantic search makes AI agents much more usable
I should’ve jumped on the “agentic coding” train earlier

You can try the full code here: semantic-search-mcp.

What tool would you plug into your AI agent if you could?

Tags: #ai #mcp #rustlang #tooling #typescript #copilot #vscode

PC Link: Clipboard, Files, and Commands, Anywher

Ojalla — Tue, 12 Aug 2025 01:46:47 +0000

PC Link: Turning a Frustration in the Computer Lab Into a Cross-Platform Remote PC Manager

It started in my university’s computer lab, on what I thought would be a normal morning.
I sat down at a lab PC and faced the same question I’ve faced too many times:

How do I move files and clipboard content between my personal PC and the machine I’m using right now without jumping through a dozen hoops?

My usual method? A roundabout mess — downloading from cloud storage, re-uploading, or emailing files to myself. Slow. Clumsy. Not exactly 21st-century magic.

I even asked GitHub Copilot for ideas. Its suggestion: email automation. Which, to me, felt like a step backwards.

So instead, I opened GPT-5, had a little back-and-forth, started tinkering, and built what would become PC Link — a cross-platform host agent with a browser-based remote control panel. In a few hours, I had my first working version.

What I didn’t expect was how much I’d enjoy certain features:

Real-time clipboard sync — copy text on the host PC, paste it instantly on any connected browser.
Peer-to-peer browser file transfer — send files directly from one browser to another without touching the host machine.
Optional remote shell execution — whitelist commands and run them from anywhere.

The result? A tool that makes my old file-transfer rituals look like sending smoke signals.

What PC Link Can Do

Clipboard sync between host PC and all connected devices (with optional remote modification).
File system browsing (sandboxed) and bidirectional file transfer.
Peer-to-peer browser-to-browser sharing via relay.
Remote shell commands with configurable whitelists.

It runs locally, or you can expose it securely with something like ngrok.

Quick Start

Clone the repo:

   git clone https://github.com/Parado-xy/pclink
   cd pclink
   npm install

Create a .env file:

   SERVER_TOKEN=$(openssl rand -hex 32)
   ROOT_DIR=/path/to/shared/folder

Start the server:

   npm start

(Optional) Expose it online with ngrok:

   ngrok http 8443

Open the browser URL, enter your token, and start connecting devices.

Why I’m Sharing This

I built PC Link to solve my own daily annoyance, but I think it can help others — especially students, remote workers, and anyone juggling multiple machines.

It’s open source, and I’d love feedback, contributions, or even just a star on GitHub:
https://github.com/Parado-xy/pclink

If you’ve ever cursed at the process of moving something between two computers, maybe this can save you a few sighs.

Security Caveats

While PC Link can be exposed over the internet, security is in your hands:

Always use strong, unique tokens.
Restrict the ROOT_DIR to a safe, non-sensitive folder.
Avoid enabling remote shell unless you fully trust your network and have a strict whitelist.
Consider running it only over HTTPS (ngrok handles this for you).
Remember: once accessible over the internet, any exposed feature is a potential attack surface.

Treat it like you would any remote access tool — with care.

Here's a linkedIn post with a demo vid: Here!

Building Cliano: A Terminal Piano in Rust

Ojalla — Fri, 11 Jul 2025 21:19:18 +0000

Cliano: A Terminal Piano in Rust

Cliano is a fun, minimal terminal-based piano application built entirely in Rust. It lets you press keyboard keys to play piano notes in real time. This project was created to keep my Rust skills sharp and explore audio programming in a command-line interface.

Features

Real-time audio playback with keypresses
Loads WAV files into memory to reduce latency
Terminal-based UI using Crossterm
Built with Rodio, Crossterm, and Clap

File Structure

.
├── sounds/          # Contains WAV files of piano notes
├── src/
│   └── main.rs      # Main application logic
├── Cargo.toml       # Project configuration

Crate Dependencies

[dependencies]
rodio = "0.17"
crossterm = "0.27"
clap = { version = "4.1", features = ["derive"] }

Step-by-Step Breakdown

1. Initialization

We start by initializing the Rodio audio output stream and sink:

let (stream, stream_handle) = OutputStream::try_default().unwrap();
let sink = Sink::try_new(&stream_handle).unwrap();

This sink handles audio playback. We also store a note_key_map which maps keyboard characters to in-memory audio buffers.

2. Loading Audio Files

fn load_keys(&mut self, dir_name: &str) {
    let mut sounds = HashMap::new();
    for entry in fs::read_dir(dir_name).unwrap() {
        let path = entry.unwrap().path();
        let file = File::open(&path).unwrap();
        let mut buffer = Vec::new();
        BufReader::new(file).read_to_end(&mut buffer).unwrap();
        // Mapping based on filename to key
        if let Some(&key) = file_to_key_map().get(path.file_name().unwrap().to_str().unwrap()) {
            sounds.insert(key, buffer);
        }
    }
    self.note_key_map = Some(sounds);
}

We read WAV files from the sounds/ directory, store them in memory, and map them to keys like 'a', 's', 'd', etc.

3. Playing Notes

When a key is pressed, we decode the associated byte buffer and play it:

fn handle_keys(&mut self, key: char) {
    if let Some(ref map) = self.note_key_map {
        if let Some(data) = map.get(&key) {
            let cursor = Cursor::new(data.clone());
            let source = Decoder::new(BufReader::new(cursor)).unwrap()
                .take_duration(Duration::from_secs(5));
            self.audio_sink.stop();
            self.audio_sink = Sink::try_new(&self.output_stream_handle).unwrap();
            self.audio_sink.append(source);
        }
    }
}

This keeps playback smooth by avoiding cold-loading audio on each press.

4. Handling Key Events

We use Crossterm to listen for keyboard input in real time:

if poll(Duration::from_millis(100)).unwrap() {
    if let Event::Key(event) = read().unwrap() {
        if event.kind == KeyEventKind::Press {
            if let KeyCode::Char(c) = event.code {
                self.handle_keys(c);
            }
        }
    }
}

5. Key-to-File Mapping

fn file_to_key_map() -> HashMap<&'static str, char> {
    HashMap::from([
        ("C4.wav", 'a'),
        ("Cb4.wav", 'w'),
        ("D4.wav", 's'),
        ("Db4.wav", 'e'),
        ("E4.wav", 'd'),
        ("F4.wav", 'f'),
        ("Fb4.wav", 't'),
        ("G4.wav", 'g'),
        ("Gb4.wav", 'y'),
        ("A4.wav", 'h'),
        ("Ab4.wav", 'u'),
        ("B4.wav", 'j'),
        ("C5.wav", 'k'),
    ])
}

You can modify this mapping to suit any custom layout.

Performance Note

Cliano uses about ~54MB of memory on Windows, mostly from storing all audio files in memory to avoid latency.

Final Thoughts

This was a blast to build. Sometimes the best way to learn (or remember) a language is to make something fun. You can find the full codebase on GitHub.

Future Improvements

Visual UI using ratatui or egui
Sustain key
Recording/playback
Octave switching

Thanks for reading!

If you want to see a live demo, check out the video:
https://youtu.be/Fppt16VJ108

A Simple chat server in rust, Shat!

Ojalla — Sat, 19 Apr 2025 15:49:03 +0000

My Rust Adventure: Building a Chat Server (Shat!) From Scratch

Alright, Rust journey time! I've been wrestling with the borrow checker (it usually wins), but I really wanted to build something networky. You know, see how data actually flies around.

Huge shout-out to Tsoding Daily on YouTube – watching him build stuff is super inspiring, and it definitely pushed me to try making my own simple TCP chat server. I called it "Shat". The goal: connect with telnet, type stuff, see other people's stuff. Simple, right? Well... mostly! I also wanted to try adding rate limiting and bans because, why not learn more?

So, grab your compiler, and let's build this thing together!

(Want the final, commented code? Jump to the repo: https://github.com/Parado-xy/shat)

Step 1: The Bare Bones (`src/main.rs`)

Every Rust project needs a main.rs. Let's start with the essentials we'll need: networking, threads, channels, time stuff, and HashMaps.

use std::collections::HashMap;
use std::net::{IpAddr, SocketAddr, TcpListener, TcpStream};
use std::result;
use std::io::{self, Write, Read};
use std::thread;
use std::sync::{mpsc, Arc}; // Arc for sharing! Mpsc for messages!
use std::sync::mpsc::{Receiver, Sender};
use std::time::{Duration, Instant};

// We'll use a simple Result alias later
type Result<T> = result::Result<T, ()>;

// --- Configuration Constants (Let's put these at the top) ---
static SAFE_MODE: bool = false; // Set true to hide IPs in logs
static BAN_LIMIT: Duration = Duration::new(60 * 10, 0); // 10 minutes
static MESSAGE_RATE_LIMIT: Duration = Duration::from_millis(500); // 0.5 seconds
static MAX_STRIKES: u8 = 5;
// --- End Constants ---


// We'll define our Message enum and Client struct here soon...


// And our client function...
// fn client(...) { ... }


// And our server function...
// fn server(...) { ... }


// And finally, the main entry point!
fn main() -> Result<()> {
    println!("Starting Shat server...");
    // TODO: Setup listener, channel, spawn threads...
    Ok(())
}

Okay, that's our skeleton. It doesn't do anything yet, but it compiles!

Step 2: Opening the Doors (`main` function)

Let's make main actually listen. We need a TcpListener and our MPSC channel (the mailbox).

// ... (keep the use statements and constants) ...

// ... (leave space for Message, Client, client, server) ...

fn main() -> Result<()> {
    let address = "0.0.0.0:4567"; // Listen on all interfaces, port 4567

    // Try to bind the listener
    let listener = TcpListener::bind(address).map_err(|err| {
        eprintln!("ERROR: could not bind {}: {}", address, err);
    })?; // The '?' handles the error nicely

    println!("INFO: Listening on address: {}", address);

    // Create the mailbox (channel)
    let (sender, receiver) = mpsc::channel::<Message>(); // We need to define Message soon!

    // Spawn the 'boss' thread (server) and give it the receiver key
    thread::spawn(|| server(receiver)); // Needs server() defined!

    // Loop to accept incoming connections
    for stream_result in listener.incoming() {
        match stream_result {
            Ok(stream) => {
                println!("INFO: Incoming connection!");
                // TODO: Handle the new stream
            }
            Err(e) => {
                eprintln!("ERROR: could not accept stream: {}", e);
            }
        }
    }

    Ok(()) // Technically unreachable, but good practice
}

// --- We still need to define Message, Client, client, server ---

Step 3: Defining the Mail (`Message` Enum) and Client State (`Client` Struct)

What kind of messages will the client threads send to the server thread? Let's define them. We also need a way for the server to remember info about each client.

// ... (use statements, constants) ...

// Enum defining the types of messages client threads can send to the server thread.
#[derive(Debug)] // Useful for debugging later
enum Message {
    // Sent when a client thread starts. Contains a clone of the client's Arc<TcpStream>.
    ClientConnected(Arc<TcpStream>), // We need Arc!
    // Sent when a client disconnects (gracefully or due to error). Contains the client's address.
    ClientDisconnected(SocketAddr),
    // Sent when a client sends data. Contains the sender's address and the data bytes.
    NewMessage(SocketAddr, Vec<u8>), // Address and the raw data
}

// Simple struct to hold client information managed by the server thread.
struct Client {
    conn: Arc<TcpStream>,   // The shared connection handle
    last_message: Instant, // For rate limiting
    strike_count: u8,      // For banning
}

// ... (leave space for client, server) ...

// ... (main function from Step 2) ...

Now our mpsc::channel::<Message>() call in main makes sense!

Step 4: Handling a Guest (`client` function)

This function runs in its own thread for each client. It needs the shared stream (Arc<TcpStream>) and a Sender to mail messages back to the server.

// ... (use statements, constants, Message, Client) ...

// Function executed by each client thread.
fn client(stream: Arc<TcpStream>, messages: Sender<Message>) -> Result<()> {
    // Get address for messages. Handle potential error early.
    let addr = match stream.peer_addr() {
        Ok(addr) => addr,
        Err(_) => {
            eprintln!("ERROR: Client connected but couldn't get address. Dropping.");
            return Err(()); // Exit this thread
        }
    };

    // Tell the server we've connected (cloning Arc is cheap)
    messages.send(Message::ClientConnected(stream.clone())).map_err(|err| {
        eprintln!("ERROR: could not send ClientConnected: {}", err);
    })?;

    println!("INFO: Client thread started for {}", addr);
    let mut buffer = vec![0; 1024]; // Buffer for reading data

    // The main read loop for this client
    loop {
        // Try reading from the stream. stream.read() works thanks to Deref coercion on Arc!
        match stream.read(&mut buffer) {
            Ok(0) => {
                // 0 bytes means client closed connection gracefully
                println!("INFO: Client {} disconnected gracefully.", addr);
                messages.send(Message::ClientDisconnected(addr)).map_err(|_| /* ignore error */)?;
                break; // Exit loop, thread will terminate
            }
            Ok(n) => {
                // Got n bytes of data! Send it to the server.
                let data = buffer[0..n].to_vec(); // Copy data from buffer
                messages.send(Message::NewMessage(addr, data)).map_err(|err| {
                     eprintln!("ERROR: could not send NewMessage: {}", err);
                })?;
            }
            Err(ref e) if e.kind() == io::ErrorKind::WouldBlock || e.kind() == io::ErrorKind::TimedOut => {
                // This happens if we set a read timeout and nothing comes in.
                // It's not a real error, just try reading again.
                continue;
            }
            Err(err) => {
                // A real read error occurred (e.g., connection reset)
                eprintln!("ERROR: reading from client {}: {}", addr, err);
                messages.send(Message::ClientDisconnected(addr)).map_err(|_| /* ignore error */)?;
                return Err(()); // Exit thread with an error
            }
        }
    }

    Ok(()) // Thread finished normally
}

// ... (leave space for server) ...

// ... (main function) ...

Step 5: The Boss Thread Logic (`server` function)

This is the big one. It receives messages and manages state.

// ... (use statements, constants, Message, Client, client function) ...

// Function executed by the single server thread.
fn server(messages: Receiver<Message>) -> Result<()> {
    let mut clients: HashMap<SocketAddr, Client> = HashMap::new();
    let mut banned_clients: HashMap<IpAddr, Instant> = HashMap::new();

    println!("INFO: Server thread started.");

    // Loop forever, processing received messages
    loop {
        // Block until a message arrives
        let msg = messages.recv().expect("ERROR: Message channel broke!");

        match msg {
            Message::ClientConnected(author_stream) => {
                let author_addr = match author_stream.peer_addr() {
                    Ok(addr) => addr,
                    Err(_) => {
                        eprintln!("ERROR: Server received ClientConnected but couldn't get address.");
                        let _ = author_stream.shutdown(std::net::Shutdown::Both); // Try to close it
                        continue; // Skip this message
                    }
                };

                let ip = author_addr.ip();
                let now = Instant::now();
                let mut is_banned = false;

                // Check ban list
                if let Some(banned_at) = banned_clients.get(&ip) {
                    if now.duration_since(*banned_at) < BAN_LIMIT {
                        println!("INFO: Rejecting banned client {}", author_addr);
                        let _ = author_stream.write(b"You are still temporarily banned.\n");
                        let _ = author_stream.shutdown(std::net::Shutdown::Both);
                        is_banned = true;
                    } else {
                        // Ban expired! Remove them.
                        println!("INFO: Ban expired for IP {}", ip);
                        banned_clients.remove(&ip);
                    }
                }

                // If not banned, add to active clients
                if !is_banned {
                    println!("INFO: Client accepted: {}", author_addr);
                    clients.insert(author_addr, Client {
                        conn: author_stream, // Store the Arc
                        last_message: now,   // Initialize timestamp
                        strike_count: 0,
                    });
                }
            } // End ClientConnected

            Message::ClientDisconnected(author_addr) => {
                println!("INFO: Client disconnected: {}", author_addr);
                // Remove from the active list
                clients.remove(&author_addr);
            } // End ClientDisconnected

            Message::NewMessage(author_addr, bytes) => {
                let now = Instant::now();
                let mut should_broadcast = true;

                // Get a mutable reference to the sending client's state
                if let Some(author) = clients.get_mut(&author_addr) {
                    // --- Rate Limit & Strike Logic ---
                    let time_since_last = now.duration_since(author.last_message);

                    if time_since_last < MESSAGE_RATE_LIMIT {
                        // Too fast! Apply strike.
                        author.strike_count = author.strike_count.saturating_add(1);
                        println!("INFO: Client {} strike {}/{} (rate limit)", author_addr, author.strike_count, MAX_STRIKES);
                        should_broadcast = false; // Don't broadcast spam

                        if author.strike_count >= MAX_STRIKES {
                            // Ban hammer!
                            println!("INFO: Banning client {} for exceeding strike limit.", author_addr);
                            banned_clients.insert(author_addr.ip(), now); // Add to ban list

                            // Try to tell them & kick them
                            let _ = author.conn.write(b"You have been banned for spamming.\n");
                            let _ = author.conn.shutdown(std::net::Shutdown::Both);

                            clients.remove(&author_addr); // Remove from active list NOW
                            continue; // Don't process this message further
                        }
                    } else {
                        // Good behavior! Update time and maybe reduce strike.
                        author.last_message = now;
                        author.strike_count = author.strike_count.saturating_sub(1); // Reduce strike
                    }
                    // --- End Rate Limit & Strike Logic ---
                } else {
                    // Got message from someone not in our list? Weird. Ignore.
                    eprintln!("WARN: Message from unknown client {}", author_addr);
                    should_broadcast = false;
                }

                // --- Broadcasting Logic ---
                if should_broadcast {
                    // Iterate over all connected clients
                    for (recipient_addr, recipient) in clients.iter() {
                        // Don't send message back to sender
                        if *recipient_addr != author_addr {
                            // Write the raw bytes. Again, write() works on &TcpStream via Arc!
                            let _ = recipient.conn.write(&bytes).map_err(|err| {
                                eprintln!("ERROR: Failed write to {}: {}", recipient_addr, err);
                                // TODO: Maybe disconnect recipient if write fails?
                            });
                        }
                    }
                }
                // --- End Broadcasting Logic ---
            } // End NewMessage
        } // End match msg
    } // End loop
    // Ok(()) // Unreachable
}

// ... (main function) ...

Step 6: Finishing Touches in `main`

We just need to make main actually use the client function and handle the Arc properly when spawning threads. We also need that read timeout.

// ... (use statements, constants, Message, Client, client, server) ...

fn main() -> Result<()> {
    let address = "0.0.0.0:4567";
    let listener = TcpListener::bind(address).map_err(|err| {
        eprintln!("ERROR: could not bind {}: {}", address, err);
    })?;
    println!("INFO: Listening on address: {}", address);

    let (sender, receiver) = mpsc::channel::<Message>();
    thread::spawn(|| server(receiver)); // Server thread started

    // Main loop: Accept incoming connections
    for stream_result in listener.incoming() {
        match stream_result {
            Ok(stream) => {
                // Set a read timeout (e.g., 5 seconds)
                // This prevents client threads from blocking forever if client hangs
                if let Err(e) = stream.set_read_timeout(Some(Duration::new(5, 0))) {
                     eprintln!("WARN: Failed to set read timeout: {}", e);
                     // Continue anyway, but thread might hang on dead client
                }

                // Clone the sender for the new client thread
                let message_sender = sender.clone();

                // Wrap the stream in Arc for safe sharing
                let stream_arc = Arc::new(stream);

                // Spawn the client thread!
                // Move the Arc and sender into the thread's closure
                thread::spawn(move || {
                    if let Err(_) = client(stream_arc, message_sender) {
                        // Error already logged in client function
                    }
                });
            }
            Err(e) => {
                eprintln!("ERROR: could not accept stream: {}", e);
            }
        }
    }
    Ok(())
}

Step 7: (Optional) Redacting IPs

If you want to hide IPs in logs, add this helper struct and use it like println!("IP: {}", Sensitive(ip));

// ... (near the top with constants) ...

// Wrapper struct to potentially redact sensitive information when displayed.
struct Sensitive<T>(T);

// Implementation of the Display trait for the Sensitive wrapper.
impl<T: std::fmt::Display> std::fmt::Display for Sensitive<T> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        if SAFE_MODE {
            write!(f, "[REDACTED]") // Use write! not writeln! here
        } else {
            write!(f, "{}", self.0) // Display the inner value
        }
    }
}

// Add Debug trait for Sensitive as well, useful if it ends up in errors
impl<T: std::fmt::Debug> std::fmt::Debug for Sensitive<T> {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        if SAFE_MODE {
            write!(f, "[REDACTED]")
        } else {
            self.0.fmt(f) // Use inner value's Debug impl
        }
    }
}

// ... (rest of the code) ...

(Remember to replace println!("INFO: Client accepted: {}", author_addr); with println!("INFO: Client accepted: {}", Sensitive(author_addr)); etc. if you use this)

We Built It!

And... that should be it! If you've followed along, putting all these pieces into main.rs, you should have a working chat server.

Run cargo run, connect with telnet localhost 4567, and chat away!

This was a super fun project. It definitely stretched my understanding of Rust's concurrency and networking basics. It's not perfect (that thread-per-client model won't scale!), but it works, and I learned a ton. Next up, maybe tackling async/await... wish me luck!

Check out the fully commented code if you got stuck or want to see the final version:
Code Repository: https://github.com/Parado-xy/shat

Happy coding!

I created a CLI-Music Player in Rust!

Ojalla — Tue, 18 Feb 2025 22:52:01 +0000

Building a Command-Line Music Player in Rust

Introduction

I built a Rust CLI Music Player that allows users to play, pause, stop, and manage their music files directly from the terminal. It supports basic playback controls, volume adjustment, and song listing.

This walkthrough will cover:

The dependencies used
How the music player was implemented
How to run the application
A guide on available commands

Dependencies

I used the following Rust crates:

clap – For command-line argument parsing.
colored – For colored terminal output.
rodio – For audio playback.
ctrlc – To handle Ctrl+C for graceful exit.

To install them, run:

cargo add clap colored rodio ctrlc

How the CLI Music Player Works

The music player follows a command-line workflow where users can:

Load songs from a specified directory.
List available songs.
Play, pause, resume, stop playback.
Adjust volume.

1. Command-Line Interface (CLI) Configuration

The application uses clap to handle command-line arguments. Users must specify a music directory:

fn cli_config() -> Command {
    Command::new("musicplayer")
        .version("0.1.0")
        .author("ojalla")
        .about("Command-line music player")
        .arg(
            Arg::new("music-dir")
                .short('d')
                .long("dir")
                .value_name("DIRECTORY")
                .help("Sets the music directory")
                .required_unless_present("how-to"),
        )
        .arg(
            Arg::new("how-to")
                .long("how-to")
                .help("Shows operation commands and how to use the application.")
                .action(clap::ArgAction::SetTrue),
        )
}

This ensures that users provide a valid music directory or request help using --how-to.

2. Handling User Input

The player reads user commands in a loop:

fn input() -> String {
    let mut user_input = String::new();

    print!("{}", "musicplayer> ".cyan().bold());
    io::stdout().flush().expect("Failed To Flush Output");

    io::stdin()
        .read_line(&mut user_input)
        .expect("Error Getting User Input");

    user_input.trim().to_string()
}

This function displays a colored prompt and waits for user input.

3. Implementing the Music Player

I created a CliPlayer struct to store the player’s state:

struct CliPlayer {
    sink: rodio::Sink,
    stream: rodio::OutputStream,
    stream_handle: OutputStreamHandle,
    is_playing: bool,
    is_paused: bool,
    main_dir: Option<String>,
    current_file: Option<String>,
    last_input: Option<String>,
    available_songs: Option<HashMap<i32, DirEntry>>,
    start_time: Option<Instant>,
}

This struct maintains:

The audio sink and output stream (rodio).
The directory containing music files.
The current playing song and status.

4. Loading Songs from a Directory

When the application starts, it loads music files from the given directory:

fn load_songs(&mut self) -> io::Result<()> {
    let mut index = 1;
    if let Some(dir) = &self.main_dir {
        if let Some(sound_map) = &mut self.available_songs {
            for entry in read_dir(dir)? {
                let entry = entry?;
                if entry.path().is_file() {
                    sound_map.insert(index, entry);
                    index += 1;
                }
            }
        }
    }
    Ok(())
}

This function reads all files in the specified directory and maps them to numbers for easy selection.

5. Playing a Song

To play a song, the application reads the file, decodes it, and plays it using rodio:

pub fn play(&mut self, sound_index: i32) -> Result<(), Box<dyn std::error::Error>> {
    if self.is_playing {
        self.sink.stop();
        self.sink = Sink::try_new(&self.stream_handle)?;
    }

    if let Some(sound_map) = &self.available_songs {
        if let Some(song) = sound_map.get(&sound_index) {
            let file = BufReader::new(File::open(song.path())?);
            let source = Decoder::new(file)?;
            self.sink.set_volume(1.0);
            self.sink.append(source.convert_samples::<f32>());
            self.is_playing = true;
            self.is_paused = false;
            self.current_file = Some(song.file_name().to_string_lossy().to_string());
            self.start_time = Some(Instant::now());
            println!("{}: Playing {}", "Now playing".green().bold(), self.current_file.as_ref().unwrap().blue());
            Ok(())
        } else {
            Err(format!("{}: Invalid song index", "Error".red()).into())
        }
    } else {
        Err("No songs available".into())
    }
}

This method:

Stops any currently playing track.
Loads and decodes the selected song.
Starts playback.

6. Implementing Playback Controls

The player handles commands like play, pause, resume, stop, and volume adjustment:

match command {
    InputCommands::Play => { /* Calls play() */ }
    InputCommands::Pause => {
        if self.is_playing {
            self.sink.pause();
            self.is_paused = true;
            println!("{}: Playback paused", "Info".yellow());
        }
    }
    InputCommands::Resume => {
        if self.is_paused {
            self.sink.play();
            self.is_paused = false;
            self.is_playing = true;
            println!("{}: Playback resumed", "Info".green());
        }
    }
    InputCommands::Stop => {
        if self.is_playing {
            self.sink.stop();
            self.is_playing = false;
            println!("{}: Playback stopped", "Info".red());
        }
    }
    InputCommands::Volume(vol) => {
        if (0.0..=1.0).contains(&vol) {
            self.sink.set_volume(vol);
            println!("{}: Volume set to {:.1}", "Success".green(), vol);
        } else {
            println!("{}: Volume must be 0.0 to 1.0", "Error".red());
        }
    }
    _ => println!("{}: Invalid command", "Error".red()),
}

These functions control playback using rodio::Sink methods like .play(), .pause(), .stop(), and .set_volume().

7. Displaying Available Songs

Users can list all available songs:

pub fn list(&self) {
    if let Some(sound_map) = &self.available_songs {
        println!("\n{}", "Available Songs:".green().bold());
        println!("{}", "-------------------------------".green());
        println!("{:<6} {:<}", "Index".to_string().bold(), "Filename".to_string().bold());
        for (index, entry) in sound_map {
            let filename = entry.file_name().to_string_lossy();
            if let Some(current) = &self.current_file {
                if filename == *current {
                    println!("{:<6} {:<} {}", index.to_string().green(), filename.green(), "▶".green());
                } else {
                    println!("{:<6} {:<}", index, filename);
                }
            } else {
                println!("{:<6} {:<}", index, filename);
            }
        }
        println!();
    }
}

Running the Application

Clone the repository:

git clone https://github.com/Parado-xy/rust-cli-music-player
cd rust-cli-music-player

Run the application with a music directory:

cargo run -- --dir /path/to/music

Use the available commands:

play <number>    # Play a song
pause            # Pause playback
resume           # Resume playback
stop             # Stop playback
volume <0.0-1.0> # Adjust volume
list             # Show available songs
status           # Show playback status
exit             # Quit the player

Conclusion

This Rust CLI Music Player is a simple but powerful terminal-based music player. It utilizes rodio for audio playback, clap for argument parsing, and colored for improved UI. Future improvements could include playlist support and file format filtering.

DEV Community: Ojalla

My First MCP Server: Semantic Code Search

Why I Built This

The Problem with AI Agents Today

Enter MCP + Seroost

Building the MCP Server

What Changes for AI Agents

Why This Matters

Setup

What’s Next

Final Thoughts

PC Link: Clipboard, Files, and Commands, Anywher

PC Link: Turning a Frustration in the Computer Lab Into a Cross-Platform Remote PC Manager

What PC Link Can Do

Quick Start

Why I’m Sharing This

Security Caveats

Building Cliano: A Terminal Piano in Rust

Cliano: A Terminal Piano in Rust

Features

File Structure

Crate Dependencies

Step-by-Step Breakdown

1. Initialization

2. Loading Audio Files

3. Playing Notes

4. Handling Key Events

5. Key-to-File Mapping

Performance Note

Final Thoughts

Future Improvements

A Simple chat server in rust, Shat!

My Rust Adventure: Building a Chat Server (Shat!) From Scratch

Step 1: The Bare Bones (src/main.rs)

Step 2: Opening the Doors (main function)

Step 3: Defining the Mail (Message Enum) and Client State (Client Struct)

Step 4: Handling a Guest (client function)

Step 5: The Boss Thread Logic (server function)

Step 6: Finishing Touches in main

Step 7: (Optional) Redacting IPs

We Built It!

I created a CLI-Music Player in Rust!

Building a Command-Line Music Player in Rust

Introduction

Dependencies

How the CLI Music Player Works

1. Command-Line Interface (CLI) Configuration

2. Handling User Input

3. Implementing the Music Player

4. Loading Songs from a Directory

5. Playing a Song

6. Implementing Playback Controls

7. Displaying Available Songs

Running the Application

Conclusion

Step 1: The Bare Bones (`src/main.rs`)

Step 2: Opening the Doors (`main` function)

Step 3: Defining the Mail (`Message` Enum) and Client State (`Client` Struct)

Step 4: Handling a Guest (`client` function)

Step 5: The Boss Thread Logic (`server` function)

Step 6: Finishing Touches in `main`