🎤

Rust製のターミナル上で動くシンプルなオーディオプレイヤー『Neiro』

2025/07/18に公開

Windowsで動作するシンプルなオーディオプレイヤー『Neiro』を作成しました。内部的にはcpalライブラリがサポートしていればどの環境でも動くはず。
https://github.com/c0b23092db/neiro

Neiro（ねゐろ）

タイトル通り、ターミナル上でオーディオファイルを再生できるコマンドです。日本語で『ねゐろ』です。
ファイラー機能はyazi経由での起動を想定しているので導入していません。yaziと合わせてお使いください。
ちなみにrodioを使った音声再生なので、tplayやascii-termのようにffmpeg、openCV、vcpkgを入れなくてもビルドできます。

インストール方法

バイナリをダウンロード

cargoからダウンロード

https://crates.io/crates/Neiro

cargo install Neiro

binstallが使えるならこちらも可能です。

cargo binstall Neiro

また、こちらの手法でもダウンロードできます。

cargo install --locked --git https://github.com/c0b23092db/neiro

開発の目的

Windows標準のファイラーを使っていると、どうしてもオーディオファイルが詰まったフォルダーを開くのが遅い問題がありました。特に大量の効果音が入っているフォルダーであればなおさら。また、Windows標準のメディアプレイヤーを開くのも少しのラグがある。
であれば、ターミナル上で音源を流すなら軽いのではないか、と考えました。しかし、WindowsにはLinuxやMacのようなターミナル上で音を流すコマンドが乏しい（ないと言ってもいい）問題があります。
なのでターミナル上で流すことができるシンプルなオーディオプレイヤーを作成しよう、というのが今回の目的です。
mpvを使えばいいというのは無視です。私はターミナル上で聞きたいのです。

使い方

ここでは軽い説明だけします。詳しい操作方法はGitHubのREADME.mdに載っているのでそちらを読んでください。・・・ここに書いてあるのとそこまで違いはありませんが。
sap.exeのヘルプを日本語訳したものです。

Simple Audio File Player in Terminal

Usage: sap.exe [オプション] <ファイル名>

Arguments:
  <ファイル名>   オーディオファイルのパス

オプション:
  -t, --timer <TIMER>    再生時間を指定する (0: 最後まで再生する) [デフォルト: 0]
  -v, --volume <VOLUME>  曲の音量を指定する [0-100] [デフォルト:50]
  -i, --interactive  インタラクティブモードで起動する。
  -h, --help         ヘルプを表示する。
  -V, --version      バージョンを表示する。

ファイルパスは必ず必要です。
起動オプションは同期再生モード（コマンド実行モード）とインタラクティブモード（TUIモード）の二つがあります。デフォルトで同期再生モードが起動し、オプションに-iを入れるとインタラクティブモードになります。

同期再生モード

sap audio.mp3

Ctrl + cで再生を止めます。オプションで音量や流す時間を調整します。以上です。

インタラクティブモード

sap -i audio.mp3

オプションの-iをつけて起動します。以下はTUIでの操作です。

Esc / q / Ctrl + c
終了
スペースキー
再開 / 一時停止
r
リプレイ
s
オーディオファイルの取り出し
↑ ↓
音量の変更。Shift同時押しで大きく変更。
← →
再生位置の変更。Shift同時押しで大きく変更。

技術スタック

オーディオ: rodio（クロスプラットフォームオーディオライブラリ）
UI: ratatui（ターミナルUI）
CLI: clap（コマンドライン引数解析）
非同期: smol（軽量非同期ランタイム）
ターミナル制御: crossterm
エラー処理: anyhow

Cargo.toml

[dependencies]
clap = { version = "4.5.41", features = ["derive"] }
crossterm = "0.29.0"
ratatui = "0.29.0"
rodio = "0.21.1"
smol = "2.0.2"
anyhow = "1.0.98"

開発

技術を説明している記事が多かったので、めぼしいところだけですがどのように作ったかの説明を行いましょう。
ディレクトリの分割方法はこのようになっています。

scr
│  main.rs
├─core
│      mod.rs
│      player.rs
├─interactive
│      app.rs
│      interactiveplayer.rs
│      mod.rs
│      ratatui.rs
│      run.rs
└─terminal
        mod.rs
        terminalplayer.rs

terminal、interactiveで処理を分離しています。
共有で使える処理はcoreに入れて処理しています。現状はplayer.rsのみです。
バージョン0.2.0ではなくバージョン0.2.1のコードですがほとんど変わりないのでこれで説明します。

src

main.rs

fn main() -> ExitCode {
    let args = Cli::parse();
    match
        if args.mode_interactive { interactive::run::run_interactive_player(&args.file_name, args.volume) }
        else { terminal::terminalplayer::one_play(&args.file_name, args.volume, args.timer) }
    {
        Ok(_) => ExitCode::SUCCESS,
        Err(e) => {
            eprintln!("{}",e);
            ExitCode::FAILURE
        }
    }
}

srcにあるmain.rsです。
最終的に返ってくる値はanyhowのResult<_>なのでmatchで処理を変えるようにしています。
こうすることによってコードを簡略的に分かりやすくできます。let shori = if ~~~とやってmatchをやるのもいいですね。

core

coreのplayer.rsにはプレイヤーとして共有で処理できる内容を入れています。

player.rs

initialize_soundplayer

core/player.rs

pub fn initialize_soundplayer() -> Result<(OutputStream,Sink)> {
    let mut stream_handle = OutputStreamBuilder::open_default_stream()
        .map_err(|e| anyhow!("Failed to initialize OutputStream in rodio：{}",e))?;
    stream_handle.log_on_drop(false);
    let sink = Sink::connect_new(&stream_handle.mixer());
    Ok((stream_handle,sink))
}

rodioのstream_handleとsinkを作成する関数です。
rodio 0.20.1ではなく0.21.1なので、よく見るlet (_stream, stream_handle) = OutputStream::try_default().unwrap();ではありません。
stream_handleとsinkを作成する関数のAPIが変わったくらいですかね。

append_one_track

core/player.rs

pub fn append_one_track(sink:&Sink,path:&Path) -> Result<Duration> {
    let file_data = File::open(path)
        .with_context(|| format!("Failed to open file：{}", path.display()))?;
    let decoder = Decoder::try_from(file_data)
        .map_err(|e| anyhow!("Failed to create decoder in rodio：{}",e))?;
    let duration = decoder.total_duration().unwrap_or(Duration::ZERO);
    sink.append(decoder);
    Ok(duration)
}

sinkにデコードしたファイルを挿入する関数です。イメージとしてはカセットを挿入する感じです。
ファイルをデコードできる場所はここしかないので、ここで合計時間を返すようにしています。

format_duration

core/player.rs

pub fn format_duration(duration:Duration) -> (u64,u64,u64,u32) {
    let hours = duration.as_secs() / 60 / 60;
    let minutes = duration.as_secs() / 60;
    let seconds = duration.as_secs() % 60;
    let millis = duration.subsec_millis();
    return (hours,minutes,seconds,millis);
}

Duration（時間）を(hours,minutes,seconds,millis)の四つに分解する関数です。TUIモードにおいて活躍してくれました。

check_and_get_path

core/player.rs

pub fn check_and_get_path(file_path:&str) -> Result<&Path> {
    let path = Path::new(file_path);
    if !path.is_file() {
        bail!("Audio file not found：{}", path.display());
    }
    Ok(path)
}

ファイルの存在を確認して&Pathを返す関数です。最初にこの処理を行って、早期リターンみたいに早く例外を返すようにします。

terminal

ファイル分割していると言っても、terminal/player.rsとmod.rsしかありません。しかも関数一つのみです。

terminalplayer.rs

terminal/terminalplayer.rs

use crate::core::player;
use std::{thread, time::Duration};
use anyhow::Result;

pub fn one_play(file_name:&str, volume:u8, mut timer:u64) -> Result<()> {
    let file_path = player::check_and_get_path(file_name)?;
    let (_stream_handle, sink) = player::initialize_soundplayer()?;
    let duration = player::append_one_track(&sink,file_path)?;
    sink.set_volume(volume.clamp(0,200) as f32 / 100.0);
    sink.play();
    let (hours,minutes,seconds,_) = player::format_duration(duration);
    if timer == 0 || duration.as_secs() < timer {
        timer = duration.as_secs();
    }
    println!("{} | {}:{:02}:{:02} | {}:{:02}:{:02}",
                file_path.file_name().unwrap().to_string_lossy().into_owned(), hours, minutes, seconds,
                timer / 60 / 60, timer / 60 % 60, timer % 60);
    thread::sleep(Duration::from_secs(timer));
    Ok(())
}

驚きでしょうがこれしかありません。ループ機能とかつけても良かったのですが・・・。

    let file_path = player::check_and_get_path(file_name)?;
    let (_stream_handle, sink) = player::initialize_soundplayer()?;
    let duration = player::append_one_track(&sink,file_path)?

先ほどのcore/playerで定義した関数を使っています。こんな感じで気軽に使えるのはいいですね。

    sink.set_volume(volume.clamp(0,100) as f32 / 100.0);
    sink.play();

volume、仕様では0から100になっていますが、u8の最大である255は使えます。ただ、音割れ対策ですね。バージョン0.2.1では0から200まで使えるようにしています。

    sink.set_volume(volume.clamp(0,100) as f32 / 200.0);

    let (hours,minutes,seconds,_) = player::format_duration(duration);
    if timer == 0 || duration.as_secs() < timer {
        timer = duration.as_secs();
    }
    println!("{} | {}:{:02}:{:02} | {}:{:02}:{:02}",
                file_path.file_name().unwrap().to_string_lossy().into_owned(), hours, minutes, seconds,
                timer / 60 / 60, timer / 60 % 60, timer % 60);

ここでは時間を表記するコードを入れています。Durationを返すようにしたのがよかったですね。
file_path.file_name().unwrap().to_string_lossy().into_owned()でファイルの名前だけ取り出すようにできます。結構出てくる印象なので覚えて損はありません。

    thread::sleep(Duration::from_secs(timer));
    Ok(())

指定した時間スリープします。これがないと再生した瞬間プログラムが終了して再生が終了します。
元々デコードした時間分流すならsink.sleep_until_end()を使っていましたが、println!との兼ね合いでこのようなコードに。

interactive

インタラクティブモード、すなわちratatuiを使う内容ですね。
run.rs、interactiveplayer.rs、app.rs、ratatui.rsに分割されています。

run.rs

interactive/run.rs

pub fn run_interactive_player(file_path:&str, volume:u8) -> Result<()> {
    enable_raw_mode()?;
    let mut terminal = ratatui::init();
    let result = App::new().run(&mut terminal, file_path, volume);
    disable_raw_mode()?;
    ratatui::restore();
    result
}

ratatuiを使う上でのおまじないみたいなものです。
ratatui::restore();は画面を初期化する用の関数です。
それからenable_raw_mode()とdisable_raw_mode()はこんな感じだそうです。

enable_raw_mode()の効果
即座の入力処理: キーを押した瞬間に入力が処理され、Enterキーを待つ必要がなくなる
特殊キーの無効化: Ctrl+C（SIGINT）やCtrl+Z（SIGTSTP）などの制御文字が通常の文字として扱われる
エコーの無効化: タイプした文字が自動的に画面に表示されなくなる
行編集機能の無効化: バックスペースやカーソル移動などの行編集機能が使えなくなる
disable_raw_mode()の効果
行単位の入力処理: Enterキーを押すまで入力がバッファされる
制御文字の復活: Ctrl+CやCtrl+Zが本来の機能を取り戻す
エコーの復活: タイプした文字が画面に表示される
行編集機能の復活: バックスペース、カーソル移動などが使える