Lib.rs

› 命令行实用程序
#和弦 #音乐 #ASCII 艺术品 #命令行 #CLI #尤克里里

bin+lib ukebox

Rust 编写的尤克里里和弦工具箱

作者 Anett Seeker

9 个版本 (破坏性更新)

0.9.2 2024年5月21日
0.9.1 2022年6月15日
0.9.0 2021年12月5日
0.8.0 2021年5月23日
0.3.0 2019年11月24日

#174 in 命令行实用程序

每月49 次下载

MIT/Apache

150KB
3.5K SLoC

ukebox

Crates.io Documentation Continuous integration license rustc

ukebox 是一个用 Rust 编写的命令行尤克里里和弦工具箱。

目录

特性

  • 通过打印 ASCII 艺术和弦图表，显示如何在尤克里里上演奏给定的和弦
  • 呈现与给定指法对应的 和弦名称，该指法以 数字和弦记号 表示
  • 支持 不同的尤克里里调音（C、D 和 G）
  • 可以在 fretboard 上呈现每个和弦的不同 位置
  • 允许您通过任何数量的半音进行和弦转换
  • 帮助您为给定的和弦序列找到好的 声部进行

安装

ukebox 的每个版本都提供预编译二进制的存档，适用于 Windows、macOS 和 Linux。

或者，可以使用 cargo 安装 ukebox。

$ cargo install ukebox

使用方法

USAGE:
    ukebox [OPTIONS] <SUBCOMMAND>

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

OPTIONS:
    -t, --tuning <TUNING>    Type of tuning to be used [default: C]  [possible values: C, D, G]

SUBCOMMANDS:
    chart         Chord chart lookup
    chords        List all supported chord types and symbols
    help          Prints this message or the help of the given subcommand(s)
    name          Chord name lookup
    voice-lead    Voice leading for a sequence of chords

当使用 Rust 运行程序时，将命令 ukebox 替换为 cargo run --release，例如 cargo run --release -- chart G。

和弦图表查找

使用子命令 chart 来查找给定和弦名称的图表。默认情况下，显示第一个匹配的和弦指法。使用标志 --all 获取相同和弦的所有可能的指法。您可以使用其他选项进一步过滤结果，例如指定应包含在和弦指法中的最小或最大品位。

USAGE:
    ukebox chart [FLAGS] [OPTIONS] <chord>

FLAGS:
    -a, --all        Print out all voicings of <chord> that fulfill the given conditions
    -h, --help       Prints help information
    -V, --version    Prints version information

OPTIONS:
        --max-fret <FRET_ID>       Maximal fret up to which to play <chord> [default: 12]
        --max-span <FRET_COUNT>    Maximal span between the first and the last fret pressed down when playing <chord>
                                   [default: 4]
        --min-fret <FRET_ID>       Minimal fret (= minimal position) from which to play <chord> [default: 0]
        --transpose <SEMITONES>    Number of semitones to add (e.g. 1, +1) or to subtract (e.g. -1) [default: 0]
    -t, --tuning <TUNING>          Type of tuning to be used [default: C]  [possible values: C, D, G]

ARGS:
    <CHORD>    Name of the chord to be shown

一些示例

$ ukebox chart G
[G - G major]

A  ||---|-o-|---|---|- B
E  ||---|---|-o-|---|- G
C  ||---|-o-|---|---|- D
G o||---|---|---|---|- G

$ ukebox chart --tuning D G
[G - G major]

B  o||---|---|---|---|- B
F#  ||-o-|---|---|---|- G
D  o||---|---|---|---|- D
A   ||---|-o-|---|---|- B

$ ukebox chart --min-fret 3 G
[G - G major]

A  -|---|-o-|---|---|- D
E  -|---|---|---|-o-|- B
C  -|---|---|---|-o-|- G
G  -|-o-|---|---|---|- B
      4

$ ukebox chart --tuning D --min-fret 3 G
[G - G major]

B   -|-o-|---|---|---|- D
F#  -|---|---|-o-|---|- B
D   -|---|---|-o-|---|- G
A   -|---|---|-o-|---|- D
       3

$ ukebox chart --transpose 1 C
[C# - C# major]

A  ||---|---|---|-o-|- C#
E  ||-o-|---|---|---|- F
C  ||-o-|---|---|---|- C#
G  ||-o-|---|---|---|- G#

$ ukebox chart --transpose -2 C
[Bb - Bb major]

A  ||-o-|---|---|---|- Bb
E  ||-o-|---|---|---|- F
C  ||---|-o-|---|---|- D
G  ||---|---|-o-|---|- Bb

$ ukebox chart --all --max-fret 5 C
[C - C major]

A  ||---|---|-o-|---|- C
E o||---|---|---|---|- E
C o||---|---|---|---|- C
G o||---|---|---|---|- G

A  ||---|---|-o-|---|- C
E o||---|---|---|---|- E
C  ||---|---|---|-o-|- E
G o||---|---|---|---|- G

A  ||---|---|-o-|---|- C
E  ||---|---|-o-|---|- G
C  ||---|---|---|-o-|- E
G o||---|---|---|---|- G

A  -|-o-|---|---|---|- C
E  -|-o-|---|---|---|- G
C  -|---|-o-|---|---|- E
G  -|---|---|-o-|---|- C
      3

和弦名称查找

使用子命令 name 来查找与给定和弦指法相对应的和弦名称。

USAGE:
    ukebox name [OPTIONS] <FRET_PATTERN>

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

OPTIONS:
    -t, --tuning <TUNING>    Type of tuning to be used [default: C]  [possible values: C, D, G]

ARGS:
    <FRET_PATTERN>    A compact chart representing the finger positions of the chord to be looked up

一些示例

$ ukebox name 2220
D - D major

$ ukebox name --tuning D 2220
E - E major

$ ukebox name 0233
Csus2 - C suspended 2nd
Gsus4 - G suspended 4th

如果品位模式包含大于9的品位号，您必须在品位号之间添加空格，并将它们放在引号内。

$ ukebox name "7 7 7 10"
G - G major

声部进行

使用子命令 voice-lead 来获取针对给定和弦序列的一些灵感，以找到良好的 和声进行。为了判断某个和声进行可能比另一个更好，ukebox 使用两个指法之间的“半音距离”（以找到良好的指法转换）以及用于演奏它们的指法的距离（以确保转换也是易于演奏的）。此功能仍处于非常实验阶段，并有望在未来进一步改进。对于其实施，我从 Pete Corey 的以下博客文章 博客 文章 中获得了许多灵感。

USAGE:
    ukebox voice-lead [OPTIONS] <CHORD_SEQUENCE>

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

OPTIONS:
        --max-fret <FRET_ID>       Maximal fret up to which to play <chord> [default: 12]
        --max-span <FRET_COUNT>    Maximal span between the first and the last fret pressed down when playing <chord>
                                   [default: 4]
        --min-fret <FRET_ID>       Minimal fret (= minimal position) from which to play <chord> [default: 0]
        --transpose <SEMITONES>    Number of semitones to add (e.g. 1, +1) or to subtract (e.g. -1) [default: 0]
    -t, --tuning <TUNING>          Type of tuning to be used [default: C]  [possible values: C, D, G]

ARGS:
    <CHORD_SEQUENCE>    Chord sequence

一些示例

$ ukebox voice-lead "C F G"
[C - C major]

A  ||---|---|-3-|---|- C
E o||---|---|---|---|- E
C o||---|---|---|---|- C
G o||---|---|---|---|- G

[F - F major]

A  ||---|---|-3-|---|- C
E  ||-1-|---|---|---|- F
C o||---|---|---|---|- C
G  ||---|-2-|---|---|- A

[G - G major]

A  ||---|-2-|---|---|- B
E  ||---|---|-3-|---|- G
C  ||---|-1-|---|---|- D
G o||---|---|---|---|- G

$ ukebox voice-lead "C F G" --tuning D
[C - C major]

B   ||-1-|---|---|---|- C
F#  ||-1-|---|---|---|- G
D   ||---|-2-|---|---|- E
A   ||---|---|-3-|---|- C

[F - F major]

B   ||-1-|---|---|---|- C
F#  ||---|---|-4-|---|- A
D   ||---|---|-3-|---|- F
A   ||---|---|-2-|---|- C

[G - G major]

B  o||---|---|---|---|- B
F#  ||-1-|---|---|---|- G
D  o||---|---|---|---|- D
A   ||---|-2-|---|---|- B

支持的和弦类型

运行 ukebox chords 获取当前支持的和弦类型和符号列表。

$ ukebox chords
Supported chord types and symbols

The root note C is used as an example.

C major - C, Cmaj, CM
C major 7th - Cmaj7, CM7
C major 9th - Cmaj9, CM9
C major 11th - Cmaj11, CM11
C major 13th - Cmaj13, CM13
C major 6th - C6, Cmaj6, CM6
C 6th/9th - C6/9, Cmaj6/9, CM6/9
C dominant 7th - C7, Cdom
C dominant 9th - C9
C dominant 11th - C11
C dominant 13th - C13
C dominant 7th flat 9th - C7b9
C dominant 7th sharp 9th - C7#9
C dominant 7th flat 5th - C7b5, C7dim5
C suspended 4th - Csus4, Csus
C suspended 2nd - Csus2
C dominant 7th suspended 4th - C7sus4, C7sus
C dominant 7th suspended 2nd - C7sus2
C minor - Cm, Cmin
C minor 7th - Cm7, Cmin7
C minor/major 7th - CmMaj7, CmM7, CminMaj7
C minor 6th - Cm6, Cmin6
C minor 9th - Cm9, Cmin9
C minor 11th - Cm11, Cmin11
C minor 13th - Cm13, Cmin13
C diminished - Cdim, Co
C diminished 7th - Cdim7, Co7
C half-diminished 7th - Cm7b5, Cø, Cø7
C 5th - C5
C augmented - Caug, C+
C augmented 7th - Caug7, C+7, C7#5
C augmented major 7th - CaugMaj7, C+M7
C added 9th - Cadd9, Cadd2
C added 4th - Cadd4

开发

提交前钩子

为了自动强制执行编码约定，Git钩子可以简化此过程。预提交钩子在每次提交之前运行，检查条件或修改文件（例如，使用 rustfmt 格式化代码）。.githooks 文件夹包含一个预提交脚本，该脚本运行 Rust 检查器 clippy 并使用 rustfmt 格式化代码。您需要安装这些工具并将 Git 配置为使用 .githooks 中的钩子。

$ rustup component add clippy
$ rustup component add rustfmt
$ git config core.hooksPath .githooks

现在，钩子将在您每次提交时运行。如果发现问题，则提交过程将中断并显示消息。手动解决 clippy 警告，使用 git add 添加更改的文件，然后重新运行 git commit，直到没有错误为止。

要忽略特定块的 clippy 检查，使用 #[allow(LINT_NAME)]，或在 lib.rs 的顶部全局使用 #![allow(LINT_NAME)]。通过添加 #rustfmt::skip 来防止 rustfmt 格式化一个块。

要绕过提交的预提交钩子，向 git commit 添加 -n 选项。

许可证

许可协议为以下之一

任选其一。

贡献

除非您明确声明，否则根据 Apache-2.0 许可证定义的，您有意提交以包含在作品中的任何贡献，都应如上所述双重许可，不得附加任何其他条款或条件。

依赖项

~4.5MB
~71K SLoC