章节： StreamDeckFS • 示例 • 为什么 • 安装 • 启动 • 配置 (图像 • 绘图 • 文本 • 事件) • 页面 • 参考 • 变量 • API • 示例配置 • Web渲染器和虚拟牌组

StreamDeckFS

StreamDeckFS是一个工具，用Python（3.9+）编写，用于配置Elgato StreamDeck（由Elgato提供）用于Linux（可能很快，我需要帮助！Darwin（mac）和Windows）

它不是一个图形界面，但如果你可以使用文件系统并创建目录和文件（不需要内容，见后文），你将拥有所有必要的功能。

它提供许多功能

• 页面管理，包括覆盖
• 图像组合，包括层、绘图和文本，所有这些都有许多配置选项
• 高级键管理（按下、释放、长按、重复、延迟等）
• 参考（稍后解释，但将其视为模板或重复页面上键的方式或具有几个差异的相同键多次的方式）
• 带有（小）逻辑和级联的变量
• API
• 网络访问
• 虚拟牌组（创建您想要的尺寸的牌组并通过浏览器访问）

streamdeckfs将查看命令行中传递的目录，并从目录和文件中读取所有配置。

在运行时，它将捕获对它们的任何更改以实时更新StreamDeck

示例

以下是使用streamdeckfs可以实现的一些示例。请记住，streamdeckfs只显示（和组合）图像，并通过提供强大的配置系统来调用程序，让您的想象力发挥余热。

示例 1：第一页

• 第一行第一个键：在按下时切换Spotify的播放/暂停，并在长按时打开StreamDeck上专用的Spotify页面（见示例 3）。显示当前播放歌曲的进度条，或者在Spotify当前未播放时在Spotify标志上显示“暂停”图标。
• 第二行和第三行的第一个键：在按下时增加/减少音量，并且可以长按以增加/减少更多。
• 最后一行的第一个键：切换静音。显示当前音量，并在静音时变为红色
• 最后一行的第二个键：在按下时切换麦克风静音，并打开一个覆盖层以增加/减少麦克风灵敏度（见示例 2）。显示当前灵敏度，并在麦克风静音时变为红色
• 第二行和第三行的最后一个键：在按下时增加/减少StreamDeck的亮度，并且可以长按以增加/减少更多。
• 最后一行的最后一个键：打开一个用于控制灯光的页面（示例未展示）

示例 2：Spotify页面

• 第一行第一个键：与第一页相同。在按下时切换播放/暂停，并在长按时返回上一页。
• 其他绿色键：上一曲/下一曲，重播曲目，在曲目中向前/向后播放
• 第二行、第三行和最后一行的第一个键：与第一页相同，用于控制音量
• 第一行第五个键：关闭Spotify页面（返回上一页）
• 第二行第四个键：当前歌曲的进度和时长
• 右上角3x3键区：当前播放专辑的封面
• 最后一行最后三个键：有关当前播放曲目的一些信息

示例 3：麦克风覆盖层

这里只有“亮”键是激活的。将覆盖层想象成一个模态窗口。

• 第一行第二个键：关闭麦克风覆盖层（返回上一页）
• 第二行和第三行的第二个键：在按下时增加/减少灵敏度，并且可以长按以增加/减少更多。
• 最后一行的第二个键：与第一页相同。在按下时切换麦克风，并在长按时关闭覆盖层。

为什么？

作为一名Linux用户，我无法使用官方应用程序，并且很快发现Linux上可用的应用程序非常有限，streamdeck-ui，因为我脑海中有很多无法完成的事情。而且我不是Linux GUI开发者，所以我更喜欢自己开发工具。然而，我使用了相同的底层Python库来与Stream Deck接口。而SnakeDeck则是在极端巧合的情况下，与StreamDeckFS同时编写的，我们双方都不知道彼此在做这件事。

安装

先决条件

• Linux（预计将来与Darwin(mac)和Windows兼容，但我目前没有这些操作系统）
• Python 3.9

系统

您需要使您的系统准备好与HID设备通信。

您首先需要安装HID API库

对于Ubuntu/Debian

sudo apt install -y libhidapi-libusb0

对于Fedora

sudo dnf install hidapi

然后您需要使您的操作系统识别StreamDeck设备

sudo tee /etc/udev/rules.d/70-streamdeck.rules << EOF
SUBSYSTEM=="usb", ATTRS{idVendor}=="0fd9", ATTRS{idProduct}=="0060", TAG+="uaccess"
SUBSYSTEM=="usb", ATTRS{idVendor}=="0fd9", ATTRS{idProduct}=="0063", TAG+="uaccess"
SUBSYSTEM=="usb", ATTRS{idVendor}=="0fd9", ATTRS{idProduct}=="006c", TAG+="uaccess"
SUBSYSTEM=="usb", ATTRS{idVendor}=="0fd9", ATTRS{idProduct}=="006d", TAG+="uaccess"
EOF
sudo udevadm control --reload-rules

最后，您需要拔下并重新插入您的StreamDeck设备以确保它们采用新的权限。

StreamDeckFS

要安装 streamdeckfs，您可以使用 pip，无论是虚拟环境还是系统 Python（提示：您需要 Python 3.9 或更高版本）。使用 pip install streamdeckfs 或 pip install --user streamdeckfs，具体取决于您的需求。

在本 README 的其余部分，我们假设软件包已正确安装，并且 streamdeckfs 可执行文件现在应该可用。

如果您不知道如何安装 Python 软件包，请访问您喜欢的搜索引擎，在那里您将找到更多关于如何操作的完整和准确的解释。

注意：除了 streamdeckfs 之外，还有一个简短版本，即 sdfs。

启动

了解您的 StreamDeck 设备

首先要做的是发现您的 StreamDeck 设备。

为此，请使用 inspect 命令

streamdeckfs inspect

它将输出有关连接的牌组的一些信息（没有其他程序必须连接到它们，因为只能连接一个牌组）。

最有用的事情是序列号，因为这将是其配置目录的名称（您可以将它放在您想要的位置）。

准备配置目录

您可以手动创建目录（我们稍后会解释如何操作），但我们提供了一个创建树状结构的命令，即 make-dirs。

streamdeckfs make-dirs SERIAL BASE_DIRECTORY

SERIAL 是从 inspect 命令中获得的序列号。请注意，如果您只有一个连接的 StreamDeck，您可以忽略此参数，因为 streamdeckfs 会自动为您找到它。

BASE_DIRECTORY 是将包含此 StreamDeck 配置目录的目录。因此，它将在 BASE_DIRECTORY 中创建（如果尚未存在）一个名为 YOUR_SERIAL_NUMBER 的目录。

在创建（或更新）树之前，您将被要求确认（除非您在命令行上传递了 --yes）。

除非您传递 --page XX，其中 XX 是要创建的页面数，否则不会创建任何页面。

确认后，streamdeckfs 将创建所有缺失的目录。

结果树将如下所示，例如对于有 3 行 5 个按键的牌组

BASE_DIRECTORY/YOUR_SERIAL_NUMBER
├── PAGE_1
│   ├── KEY_ROW_1_COL_1
│   ├── KEY_ROW_1_COL_2
│   ├── KEY_ROW_1_COL_3
│   ├── KEY_ROW_1_COL_4
│   ├── KEY_ROW_1_COL_5
│   ├── KEY_ROW_2_COL_1
│   ├── KEY_ROW_2_COL_2
│   ├── KEY_ROW_2_COL_3
│   ├── KEY_ROW_2_COL_4
│   ├── KEY_ROW_2_COL_5
│   ├── KEY_ROW_3_COL_1
│   ├── KEY_ROW_3_COL_2
│   ├── KEY_ROW_3_COL_3
│   ├── KEY_ROW_3_COL_4
│   ├── KEY_ROW_3_COL_5
├── PAGE_2
...

现在您已准备好配置按键。以下是配置的最直接方法

• 将图像文件（或创建符号链接）复制到 KEY... 目录（在 PAGE_1 目录中，因为显示的第一页是编号最低的页）并命名为 IMAGE。这是将显示在按键上的图像。
• 将脚本/程序（或创建符号链接）复制到同一 KEY... 目录并命名为 ON_PRESS。这是当按键被按下时将执行的脚本/程序。

就这样；您现在知道如何以最简单的方式配置 StreamDeck。我们稍后会看到许多配置选项。

PS：您可以有 IMAGE 没有 ON_PRESS 或 ON_PRESS 没有 IMAGE。

运行 streamdeckfs

现在您已经有了配置目录，请运行

streamdeckfs run SERIAL CONFIG_DIRECTORY

瞧！

请注意，与 make-dirs 一样，如果您只有一个连接的 StreamDeck，则 SERIAL 参数是可选的。

CONFIG_DIRECTORY 可以是确切的目录，即 BASE_DIRECTORY/YOUR_SERIAL_NUMBER，或者 make-dirs 中使用的目录，即 BASE_DIRECTORY（然后 streamdeckfs 将完成它。如果您只有一个连接的牌组，并且不想记住序列号，这很有用，因此在这种情况下，命令可以是仅 streamdeckfs run BASE_DIRECTORY）。

现在您已运行 StreamDeck，尝试为另一个按键添加图像（在第一页上）。您会看到牌组自动更新。也许您已经开始看到无限的可能性。

如果您有许多 StreamDeck，每个都有一个配置目录（例如，如果 2 个牌组 BASE_DIRECTORY/YOUR_SERIAL_NUMBER_1 和 BASE_DIRECTORY/YOUR_SERIAL_NUMBER_2，您有很多选择

• 运行时不传递任何序列号并传递 BASE_DIRECTORY：它将为在 BASE_DIRECTORY 中具有配置目录的所有牌组运行
• 通过传递一个或多个序列号并传递 BASE_DIRECTORY 运行：它将运行所有在 BASE_DIRECTORY 中的配置目录下的所需套牌。
• 不传递任何序列号并传递序列配置目录 BASE_DIRECTORY/YOUR_SERIAL_NUMBER_1 运行：它将只为此套牌运行。

您还可以运行多个程序实例，每个套牌一个（这样您可以轻松停止其中一个）。有两种方法可以做到这一点

• 对于每个套牌，不传递任何序列号并传递序列配置目录 BASE_DIRECTORY/YOUR_SERIAL_NUMBER_1
• 对于每个套牌，传递其序列号并传递全局或序列配置目录，即 BASE_DIRECTORY 或 BASE_DIRECTORY/YOUR_SERIAL_NUMBER_1

请注意，streamdeckfs 可以在 StreamDecks 连接之前或配置目录准备就绪之前启动。它将耐心等待所有内容都准备好以便渲染 StreamDeck。如果这些目录后来变得不可用，或者如果 StreamDecks 被拔掉，它将停止渲染它们并等待它们再次就绪。

图片

您可以在 StreamDeck 上配置两个东西：“外观”，即显示在按键上的内容，以及当您“操作”它们时发生的事件。

但首先，让我们谈谈配置是如何工作的。

配置格式

所有操作都是在文件名下完成的。比如说你想用选项 foo 配置 IMAGE，其值为 bar，那么你必须将文件从 IMAGE 重命名为 IMAGE;foo=bar。

如果你要添加一个名为 my-key 的名称（稍后解释），文件名将是 IMAGE;foo=bar;name=my-key。

所以需要知道的三件事是

• 如果图像（或事件、或文本）有一些配置选项，"正常"名称（如 IMAGE、ON_PRESS...）与配置之间用分号分隔：IMAGE;here=is;the=config
• 键/值配置对用 = 在键和值之间分组：key=value
• 不同的配置对用分号分隔：key1=value1;key2=value2

注意，配置选项的顺序不是必须的。

关于限制，有一些事情需要考虑

• 有些字符不允许出现在文件名中（仅在 Linux 上的 /）
• 文件名的长度有限（通常在 Linux 上为 256 个字符）

常见配置选项

两个配置选项是每个目录或文件共有的

名称

它是页面、按键、图像、事件或文本的名称。它可以是你想要的任何内容，并且可以用来“引用”其他页面、按键、图像、事件和文本。例如，如果您有一个专门用于显示 Spotify 按键的页面，您可以命名页面目录为 PAGE_50;name=spotify，这样当您想要有一个按键转到此页面时，您将能够使用页面编号或名称。使用名称允许您按您想要的顺序重新排序页面。我们稍后会看到如何使按键在按下时显示不同的页面。

禁用

要使 streamdeckfs 忽略页面、图像、文本、事件...，您可以使用 disabled 选项，这是一个标志，表示只需添加 ;disabled 就足以将其禁用，但您也可以设置布尔值 ;disabled=true 或 ;disabled=false。

启用

它是 disabled 的完全相反。用作标志 enabled 仅或通过 enabled=true（等价于 disabled=false）或 enabled=false（等价于 disabled=true）

在使用 变量 时很有用。只能使用 enabled 或 disabled 中的一个。

配置外观（图像、绘图、文本）

首先，我们来谈谈支持的图像格式。您可以使用由 Python 库 pillow 支持的所有图像格式。例如，jpeg、png、gif（目前尚未处理动画 gif）。透明度级别（"alpha 层"）将被尊重。

图像将被调整大小以适应键：一个 72 或 96 像素的正方形，具体取决于您拥有的 StreamDeck 型号（inspect 命令会提供这些信息）。保持原始图像的比率，透明区域取决于比率，位于顶部/底部或左侧/右侧。

图像层

要在键上显示内容，最简单的方法是将图像（或链接）拖放到相应的 KEY... 目录并命名为 IMAGE。

但您可以使用图层来制作高级的合成，例如背景、图标和覆盖层。

选项 "图层"

要将图像设置为图层，请将 layer 配置选项设置为数字：IMAGE;layer=1、IMAGE;layer=2... 图层将按数字顺序依次绘制。此外，请注意，当至少有一个图像定义了图层编号时，默认图像（即不带 layer 配置的 IMAGE）将被忽略。

如果两个图像具有相同的图层编号，则显示最新的一个，其他将被忽略。

因此，我们可以有很多图层，它们将重叠绘制。但在这种情况下，我们只能看到最上面的图层，对吗？并不完全是这样。您可以在每个图层上应用许多配置选项，如下所示。

以下列表按照在图层上应用它们的顺序列出配置选项（文件名中的顺序不是必需的）。

请注意，以下选项也适用于没有定义图层的单个图像。

选项 "裁剪"

使用 crop 选项，您可以选择仅显示图像的特定部分。坐标可以定义为从源图像的像素或百分比。

它必须这样定义：crop=LEFT,TOP,RIGHT,BOTTOM，表示用于“裁剪”矩形的两个点（x,y），基于（0,0）坐标在图像的左上角：左上角和右下角。值如下：

• LEFT：从左侧的像素或百分比（原始宽度的百分比）距离
• TOP：从顶部的像素或百分比（原始高度的百分比）距离
• RIGHT：从右侧的像素或百分比（原始宽度的百分比）距离
• BOTTOM：从顶部的像素或百分比（原始高度的百分比）距离

示例：在所有图像示例中，我们将使用 Elgato 标志（在透明上变为白色），默认情况下看起来像这样（示例来自真实设备的照片）

• 在 100x100 像素的图像上应用 IMAGE;crop=10,10,90,90，将在所有边移除 10 像素的边框

• IMAGE;crop=0,0,33.33%,33.33% 将仅保留图像的左上三分之一（它可以用于在 9 键正方形上显示图像，每个键包含相同的图像，但具有不同的裁剪配置）

裁剪后，保留的部分将成为其他配置选项的源图像。

除了 crop 之外，还可以覆盖单独的部分。例如，crop=10,10 10,10;crop.1=20 等于 crop=10,20,10,10。为了使其生效，必须定义 crop。索引（crop.1 中的 1 从 0 开始：0 到 3 的 4 个部分可以覆盖。现在可能看起来不是很有用，但稍后我们会看到它非常有用。）

为了更易于阅读，您可以使用 crop.left、crop.top、crop.right 和 crop.bottom 而不是 crop.0、crop.1、crop.2 和 crop.3。

选项 "旋转"

rotate 选项接受源图像（或之前选项已更新的图像），并将其顺时针旋转给定角度。

它必须这样定义：rotate=角度，其中：

• 角度：从0到360度的角度，或者以百分比表示（100%=360度）（可以是负数或超过360/100%，在这种情况下，它将按预期工作）

示例

• IMAGE;rotate=180 将图像颠倒

• IMAGE;rotate=50% 同样，但以百分比表示

旋转后，更新后的图像将成为其他配置选项的源图像。

选项 "margin"

margin 选项允许通过定义所有边的边距，将源图像（或之前选项已更新的图像）放置在关键区域。其工作方式是从原始关键尺寸中移除边距，并将图像适应剩余区域，同时保持纵横比。

值可以以像素为单位从关键尺寸定义，也可以以百分比表示（使用百分比可以在关键尺寸不同的情况下保持相同的渲染效果）

它必须这样定义：margin=上,右,下,左，其中：

• 上：顶部边距的高度，以像素或百分比（关键高度）表示
• 右：右侧边距的宽度，以像素或百分比（关键宽度）表示
• 下：底部边距的高度，以像素或百分比（关键高度）表示
• 左：左侧边距的宽度，以像素或百分比（关键宽度）表示

示例

• IMAGE;margin=10,10,10,10 在所有尺寸上创建10像素的边距

• IMAGE;margin=0,33.33%,0,33.33% 如果关键尺寸中间三分之一（左、右各33.33%的边距，因此中间有33.33%的空间）适应图像

除了 margin 之外，还可以覆盖单个部分。例如，margin=10,10 10,10;margin.1=20 等同于 margin=10,20,10,10。为了使其生效，必须定义 margin。索引（margin.1 中的 1 从0开始：4个部分（从 0 到 3）可以覆盖。现在可能看起来没有用，但稍后我们会看到它非常强大。

为了更易读，您可以使用 margin.top、margin.right、margin.bottom 和 margin.left 而不是 margin.0、margin.1、margin.2 和 margin.3。

选项 "colorize"

colorize 选项接受一种颜色，并将图像中的所有颜色替换为这种颜色，同时保留透明度层（不透明度）。例如，如果您想以特定颜色显示一个黑色带有透明度的图标，它将非常有用。

它必须这样定义：colorize=颜色，其中：

• 颜色：要使用的颜色。它可以是一个常见的HTML颜色名称（红色、绿色、蓝色等）或十六进制RGB值，如 #ff0000（这里，纯红色）。颜色名称或十六进制值不区分大小写。

示例

• IMAGE;colorize=red 将图像着色为红色

• IMAGE;colorize=#00FFFF 将图像着色为青色

选项 "opacity"

opacity 选项允许定义图像的不透明度，即下层可见程度。

它必须这样定义：opacity=数字，其中：

• 数字：不透明度级别，从0到100，0表示最不透明（完全透明，层将完全不可见），100表示最不透明（完全不透明，除了已经透明的部分）

对于图像中已经部分透明的部分，随着不透明度的降低，它们将变得更加透明。

示例

• IMAGE;opacity=100 完全不会改变透明度
• IMAGE;opacity=50 使图像50%透明（这里带有红色背景）

选项 "file"

如果您不想将图像复制或链接到IMAGE...文件中的KEY...目录，您可以使用file配置选项来定义要渲染的图像的路径。

您必须遵守已知的文件名限制（最大长度和不能有斜杠/），并避免使用分号;，因为它被解释为路径的结束（因为它是配置选项的分隔符）。对于斜杠，您可以用slash选项中定义的任何字符序列替换它（默认为\\）。对于分号，您可以用semicolon选项中定义的任何字符序列替换它（默认为^）。

请注意，当设置此选项时，IMAGE...文件可以为空，因为它的内容将被忽略。并且您不能同时设置file和draw选项（有关最后一个选项，请参阅Drawings）。

它必须这样定义：file=PATH，其中

• PATH：要渲染的图像文件的路径。它可以以~开头。

示例

• IMAGE;file=|home|myself|Images|logo.png;slash=|将使用位于/home/myself/Images/logo.png的图像。请注意，/被替换为|，如slash配置选项中定义的那样。
• IMAGE;file=\\home\\myself\\Images\\logo.png与上面相同，但使用未传递时的slash配置选项的默认值。

当引用的图像发生变化时，密钥将更新。

如果您不想处理特殊字符，您可以使用file=__inside__并在文件的第一行中写下图像的路径。

选项 "slash"

在使用file选项时，在文件名中不可能使用斜杠，因此您可以用slash选项中定义的任何字符或字符序列替换它。如果没有定义，则使用默认值\\。

它必须这样定义：slash=REPLACEMENT，其中

• REPLACEMENT：在command配置选项中用于替换/字符的字符或字符序列。

示例

• IMAGE;file=|home|myself|Images|logo.png;slash=|将使用位于/home/myself/Images/logo.png的图像。请注意，/被替换为|，如slash配置选项中定义的那样。
• IMAGE;file=XXXhomeXXXmyselfXXXImagesXXXlogo.png;slash=XXX与上面相同，但使用XXX代替|。
• IMAGE;file=\\home\\myself\\Images\\logo.png与上面相同，但使用未传递时的slash配置选项的默认值。

选项 "semicolon"

在使用file选项时，在文件名中不可能使用分号，因此您可以用semicolon选项中定义的任何字符或字符序列替换它。如果没有定义，则使用默认值^。

它必须这样定义：semicolon=REPLACEMENT，其中

• REPLACEMENT：在command配置选项中用于替换;字符的字符或字符序列。

示例

• IMAGE;file=\\home\\myself\\Images\\logo^version2.png将使用默认值（\\）和默认值（^）使用位于/home/myself/Images/logo;version2.png的图像。
• IMAGE;file=|home|myself|Images|logo,version2.png;slash=|;semicolon=,与上面相同，但使用|代替斜杠，使用,代替分号。

绘图

除了图像文件外，层还可以是简单的绘图：点、线、矩形/多边形、圆/椭圆、拱、弦和饼图。

绘图可以用来添加进度条（水平、圆形）、文本标题和文本内容之间的分隔线等。

绘图层的命名方式与图像相同（即，以IMAGE;开头）但可以是空文件（或您想要的任何文件，内容将被忽略），并使用draw=KIND和其他配置选项定义，这些选项取决于绘图类型。

如上所述，绘图是图像层，按这种方式定义，因此所有上述针对图像的配置选项也适用于绘图。绘图就像是图像的来源，因此所有上述图像的配置选项都可以使用。

关于绘图配置选项的一些常见知识

• 坐标基于键的大小，基于（0,0）坐标位于图像的左上角
• 坐标可以以像素或百分比给出。如果是百分比，则将从键大小的宽度和高度中获取
• 坐标可以是负数
• 坐标以一系列 X,Y 对给出，用逗号分隔，例如两个点为 X1,Y1,X2,Y2
• 如果未定义，则默认线（轮廓）颜色为 白色
• 线的宽度，以像素为单位，如果超过1，则将均匀分布在线的“中心”周围
• 如果未定义，则默认线宽为 1
• 默认“填充”未设置，即默认情况下，如果不定义任何颜色/宽度，将得到一条细白线
• 颜色（轮廓和填充）可以设置为名称、简单的十六进制值（#RRGGBB）或具有透明度的十六进制值（#RRGGBBAA）
• 角度可以用度数（从0到360，但可以是负数或超过360，0是午夜）或百分比（100%=360度）表示

对于 coords 和 angles（下面将描述），除了完整的配置选项外，还可以覆盖各个部分。例如，angles=0,90;angles.1=180 等同于 angles=0,180。为此，必须定义完整的配置选项。索引（angles.1 中的 1 从 0 开始：对于角度，可以覆盖 2 个部分（0 和 1），对于坐标，必须是原始坐标中存在的索引。现在可能看起来不太有用，但稍后我们将看到它非常强大。

类型“points”

可以一次用相同的颜色绘制许多点（像素）。

必须这样定义：draw=points;coords=COORDS;outline=COLOR，其中

• COORDS：一系列 X,Y 对，每个都代表一个要绘制的点
• COLOR：点的颜色。可选

无法定义点的“大小”：它始终是一个像素。

示例

• IMAGE;draw=points;coords=50%,50% 将在键的中心绘制一个白色点

• IMAGE;draw=points;coords=10,10,20,20,30,30;outline=yellow 将在坐标 (10,10)、(20,20) 和 (30,30) 处绘制 3 个黄色点

类型“line”

线绘制在给定的不同点之间（至少两个）。

必须这样定义：draw=line;coords=COORDS;outline=COLOR;width=WIDTH，其中

• COORDS：一系列 X,Y 对，每个都代表线的起点，如果不是第一个，则是前一个的终点
• COLOR：线的颜色。可选
• WIDTH：线的宽度。可选

示例

• IMAGE;draw=line;coords=0,0,100%,100% 将绘制从左上角到右下角的白色对角线

• IMAGE;draw=line;coords=10,10,20,10,10,20,20,20;outline=red;width=2 将在左上角附近绘制一个厚度为 2 像素的红色“Z”

类型“rectangle”

矩形由两个点表示：左上角和右下角。

必须这样定义：draw=rectangle;coords=X1,Y1,X2,Y2;outline=LINE_COLOR;width=WIDTH;fill=FILL_COLOR;radius=RADIUS，其中

• X1,Y1：左上角的坐标
• X2,Y2：右下角的坐标
• LINE_COLOR：线的颜色。可选
• WIDTH：线的宽度。可选
• FILL_COLOR：填充矩形内部的颜色。可选
• RADIUS：圆的半径，用于创建圆角矩形。可选

示例

• IMAGE;draw=rectangle;coords=0,0,100%,100%;fill=red;width=0 将用红色填充整个键区域（注意，您可以使用下面描述的 draw=fill 来实现相同的效果）

• IMAGE;draw=rectangle;coords=10,10,40,40;outline=blue;width=5;fill=#0000FF80 将在左上区域绘制一个粗蓝色的矩形，内部填充半透明蓝色（通过结尾的 80 实现）

• IMAGE;draw=rectangle;coords=10%,10%,90%,90%;radius=20 将绘制一个带圆角的矩形

类型 "fill"

fill 类型是覆盖整个键面而没有轮廓的矩形的快捷方式。

因此，IMAGE;draw=fill;fill=red 等同于 IMAGE;draw=rectangle;coords=0,0,100%,100%;width=0;fill=red。只需要指定 fill 配置选项（参见上面的类型 rectangle）。

类型 "polygon"

多边形类似于 line，在最后一点和第一点之间有一条线，并且可以填充颜色。有一个缺点：由于所使用的库的限制，无法定义线的宽度（为此，可以添加一个具有相同 coords 但在末尾添加第一个 X,Y 以闭合线的 draw=line 层）。

必须这样定义：draw=polygon;coords=COORDS;outline=LINE_COLOR;fill=FILL_COLOR，其中

• COORDS：一组 X,Y 对，每个都是一个多边形的“角落”。
• LINE_COLOR：线的颜色。可选
• FILL_COLOR：填充多边形内部的颜色。可选。

示例

• IMAGE;draw=polygon;coords=50%,0,100%,50%,50%,100%,0,50%;color=yellow 将绘制一个接触四边中点的黄色菱形

类型 "ellipse"

椭圆由其边界框定义，边界框由两个点表示：框的左上角和右下角。如果边界框的宽度和高度相等，则得到一个圆。

必须这样定义：draw=ellipse;coords=X1,Y1,X2,Y2;outline=LINE_COLOR;width=WIDTH;fill=FILL_COLOR，其中

• X1,Y1：边界框左上角的坐标
• X2,Y2：边界框右下角的坐标
• LINE_COLOR：线的颜色。可选
• WIDTH：线的宽度。可选
• FILL_COLOR：填充椭圆内部的颜色。可选。

示例

• IMAGE;draw=ellipse;coords=0,0,100%,100% 将绘制一个接触四边中点的圆

• IMAGE;draw=ellipse;coords=10,10,60,40;outline=blue;width=5;fill=#0000FF80 将绘制一个在上部区域绘制的粗边扁平蓝色椭圆，内部填充半透明的蓝色（通过结尾的 80）

类型 "arc"

弧是椭圆轮廓的一部分。它由椭圆的边界框定义（参见上面的 ellipse），以及两个角度（起始和结束）。

必须这样定义：draw=arch;coords=X1,Y1,X2,Y2;angles=START,END;outline=LINE_COLOR;width=WIDTH，其中

• X1,Y1：边界框左上角的坐标
• X2,Y2：边界框右下角的坐标
• START：弧的起始角度。
• END：弧的结束角度。弧按顺时针方向绘制。
• LINE_COLOR：线的颜色。可选
• WIDTH：线的宽度。可选

示例

• IMAGE;draw=arc;coords=10%,10%,90%,90%;angles=0,270;width=5;outline=red 将绘制一个表示 75% 循环进度条的粗红色弧，从午夜开始，到 9 点结束

• IMAGE;draw=arc;coords=10%,10%,90%,90%;angles=0,75%;width=5;outline=red 相同，但结束角度以百分比表示

类型 "chord"

弦类似于弧，在其两端之间有一条线，并且可以填充颜色。

必须这样定义：draw=chord;coords=X1,Y1,X2,Y2;angles=START,END;outline=LINE_COLOR;width=WIDTH;fill=FILL_COLOR，其中

• X1,Y1：边界框左上角的坐标
• X2,Y2：边界框右下角的坐标
• START：弧的起始角度。
• END：弧的结束角度。弧按顺时针方向绘制。
• LINE_COLOR：线的颜色。可选
• WIDTH：线的宽度。可选
• FILL_COLOR：填充弦内部的颜色。可选。

示例

• IMAGE;draw=chord;coords=20%,20%,80%,80%;angles=270,90 将在上半部分绘制一个封闭的半圆

• IMAGE;draw=chord;coords=20%,20%,80%,80%;angles=-25%,25% 相同，但角度以百分比表示

类型 "pieslice"

弦类似于弧，在其两端与边界框中心之间有一条线。它可以填充颜色。

必须这样定义：draw=pieslice;coords=X1,Y1,X2,Y2;angles=START,END;outline=LINE_COLOR;width=WIDTH;fill=FILL_COLOR，其中

• X1,Y1：边界框左上角的坐标
• X2,Y2：边界框右下角的坐标
• START：弧的起始角度。
• END：弧的结束角度。弧按顺时针方向绘制。
• LINE_COLOR：线的颜色。可选
• WIDTH：线的宽度。可选
• FILL_COLOR：填充饼图内部的颜色。可选。

示例

• IMAGE;draw=pieslice;coords=20%,20%,80%,80%;angles=0,90 将在右上象限绘制一个四分之一圆，"指向"中心

• IMAGE;draw=pieslice;coords=-50%,-50%,50%,50%;angles=90,180;width=4 将在左上角绘制一个指向左上角的四分之一圆

文本

图像非常适合带有意义的键，但有一种显示文本的方法可能很有用，可以在键上添加可见的标题或展示一些信息。

文本不是像图像层和绘图那样定义的，而是单独定义。最基本的文本是 TEXT;text=foo。它将在所有图像层（如果有的话）上方以白色在左上角写入“foo”。或者，它可以直接是 TEXT，不使用 text 配置选项，在这种情况下，文本将从文件内容中读取。

与层一样，你可以使用 line=XX 配置选项（与图像/绘图的 layer=XX 配置选项相同）来使用一行或多行文本。

文本的“行”可以有不同的配置选项，并将按照其数字顺序堆叠写入。请注意，所有 IMAGE 层将在文本行之前绘制。

所有文本都将使用相同的字体（Roboto），该字体有许多“样式”（重量和斜体的组合）。表情符号通过 Noto Color Emoji 字体渲染（你可以直接使用表情符号，如 ❤️，或使用 :heart: 这样的表情符号代码）。这两个字体都包含在 streamdeckfs 包中。

默认情况下，文本不会被换行，并且将被截断以适应一行。有关更改此行为，请参阅下面的 wrap 和 scroll 选项。

所有连续的空白都将合并为一个空格。并且 ^ 和 \\ 将被替换为 ; 和 /（可以通过 slash 和 semicolon 配置选项进行更改）。

文本的配置选项包括

选项 "line"

这是要写入的行号。如果定义了多行，则只需要此选项。并且像层一样，如果存在多行，如果其中一行没有 line= 配置选项，则将被忽略。

选项 "text"

如果已定义，则它是要写入的文本，而不是从文件内容中读取。换行符被替换为空格（除非启用了换行。

当使用文件名中的 text 设置文本时，请务必考虑有关文件名限制的规则：没有 / 并且长度不超过操作系统授权的最大长度（Linux 上为 256 个字符）。另外一条规则：文本不能包含分号，因为它被解释为文本的结束（因为它是配置选项分隔符）

如果您需要绕过这些规则，请参阅下面的 file 配置选项。

文本必须这样定义：text=foo with space | or whatever (really)。

选项 "size"

字体的大小。

它必须这样定义：size=SIZE，其中

• SIZE：要写入的文本的大小，以像素为单位，或者以键高度的百分比（将转换为像素）。默认为 20%。

示例

• TEXT;text=foobar;size=10 将绘制一个非常小的文本

• TEXT;text=foobar;size=40 将绘制一个非常大的文本

选项 "fit"

当您想要文本占据最大可用空间时，此配置选项可以替换 size 选项。

它与 wrap 兼容，即如果未激活换行，它将找到一种字体大小，使整个文本适合一行。

如果激活了 fit，则 valign 和 align 的默认值不同：valign 为 middle（而不是 top），而 align 为 center（而不是 left）。

此配置选项特别有用，可以显示尽可能大的单个表情符号。

它必须这样定义

• fit 或 fit=true 用于使文本适应大小
• fit=false 用于不适应文本大小（与未定义fit选项相同）

示例

• TEXT;text=😂;fit 或 TEXT;text=😂;fit=true 将使表情符号尽可能大

• TEXT;text=😂;fit=false 或 TEXT;text=😂 将使用默认大小

选项 "weight"

这是要使用的字体粗细。

它必须定义为这样的格式：weight=WEIGHT，其中

• WEIGHT：可用粗细度之一：thin、light、regular、medium、bold、black（从细到粗的顺序排列）

默认为 medium。

示例

• TEXT;text=foobar;weight=thin 将绘制非常细的文本

• TEXT;text=foobar;weight=black 将绘制非常粗的文本

选项 "italic"

这是一个标志，用于指示文本是否需要写成斜体。

它必须这样定义

• italic 或 italic=true 使用斜体
• italic=false 不使用斜体（与未定义italic选项相同）

示例

• TEXT;text=foobar;italic 或 TEXT;text=foobar;italic=true 将绘制斜体文本

• TEXT;text=foobar;italic=false 或 TEXT;text=foobar 将绘制常规文本（非斜体）

选项 "align"

文本的水平对齐方式。

它必须这样定义：align=ALIGN，其中

• ALIGN：要使用的水平对齐方式，可以是 left、center 和 right 之间的一个。如果未设置，默认为 left。

示例

• TEXT;text=foobar;align=center 将在键中水平居中文本

选项 "valign"

文本的垂直对齐方式。

它必须这样定义：valign=ALIGN，其中

• ALIGN：要使用的垂直对齐方式，可以是 top、middle 和 bottom 之间的一个。如果未设置，默认为 top。

示例

• TEXT;text=foobar;valign=middle 将在键中垂直居中文本

选项 "color"

要写入的文本的颜色。

它必须这样定义：color=COLOR，其中

• COLOR：要使用的颜色。它可以是一个常见的HTML颜色名称（红色、绿色、蓝色等）或十六进制RGB值，如 #ff0000（此处为纯红）。颜色名称或十六进制值不区分大小写。

示例

• TEXT;text=foobar;color=red 将用红色写入文本

选项 "opacity"

opacity 选项允许定义文本的透明度，即下面的层将如何可见。

它必须这样定义：opacity=数字，其中：

• NUMBER：透明度级别，从0到100，0表示最不透明（完全透明，文本将完全不可见），100表示最透明（完全不透明）

示例

• TEXT;text=foobar;opacity=100 不会改变透明度
• TEXT;text=foobar;opacity=50 使文本50%透明（此处为红色背景）

选项 "wrap"

这是一个标志，用于定义如果文本在一行中放不下是否需要换行。如果没有设置（默认），文本将被截断以保持在同一行。

在换行模式下，文本将在单词之间分割，如果某个单词太长无法放入一行，它将被分割成至少两部分。

它必须这样定义

• wrap 或 wrap=true 用于在行中换行文本
• wrap=false 用于不换行文本（与未定义wrap选项相同）

示例

• TEXT;text=foobar baz qux;wrap 或 TEXT;text=foobar baz qux;wrap=true 如果文本太长将进行换行

• TEXT;text=foobar baz qux;wrap=false 或 TEXT;text=foobar baz qux 将不换行

选项 "margin"

margin 选项允许通过定义所有方向的边距，将文本放置在键区域中。其工作方式是从原始键大小中去除边距，并在剩余区域中适应文本。

然后，将在边距限制的区域内应用 align 和 valign 选项（对于 wrap 选项也是一样：文本将在多行中显示，但只在此区域内显示）。

值可以以像素为单位从关键尺寸定义，也可以以百分比表示（使用百分比可以在关键尺寸不同的情况下保持相同的渲染效果）

它必须这样定义：margin=上,右,下,左，其中：

• 上：顶部边距的高度，以像素或百分比（关键高度）表示
• 右：右侧边距的宽度，以像素或百分比（关键宽度）表示
• 下：底部边距的高度，以像素或百分比（关键高度）表示
• 左：左侧边距的宽度，以像素或百分比（关键宽度）表示

示例

• TEXT;text=foobar;margin=70%,0,0,0 将只在底部的70%显示文本

选项 "scroll"

当文本未全部可见时，scroll 选项很有用。如果未设置换行选项，则允许水平滚动文本；如果没有，则垂直滚动。

必须这样定义：scroll=SIZE，其中

• SIZE：每秒滚动的像素数。可以是负数，也可以是百分比（如果启用 wrap，则为键高度的百分比；如果没有，则为键宽度的百分比）

如果文本足够小，可以适应其定义的区域（整个键或内部边距留下的区域），则不会出现滚动。

关于对齐的说明，如果文本需要滚动因为它不适应

• 如果没有启用 wrap，则将忽略 align 选项，文本将

  • 如果滚动为正值：左对齐（并将从右向左移动）
  • 如果滚动为负值：右对齐（并将从左向右移动）

• 如果启用 wrap，则忽略 valign 选项，文本将

  • 如果滚动为正值：顶部对齐（并将从底部向上移动）
  • 如果滚动为负值：底部对齐（并将从顶部向下移动）

示例

• TEXT;text=this is a long text for a single line;wrap=false;scroll=20 将保持文本在一行，但将以每秒20像素的速度滚动

https://user-images.githubusercontent.com/193474/120557135-c38ef400-c3fd-11eb-8f2a-9cf45d4e3f79.mp4

• TEXT;text=this is a very long text that even when wrapped, will not fit;wrap;scroll=20 将换行文本并以每秒20像素的速度滚动

https://user-images.githubusercontent.com/193474/120557406-26808b00-c3fe-11eb-8477-b551bb2937c6.mp4

选项 "file"

如果您不想将文本复制或链接到 KEY... 目录中的 TEXT... 文件，您可以使用 file 配置选项来定义要渲染的文本的路径。然后读取文件以获取文本。

您必须遵守已知的文件名限制（最大长度和不能有斜杠/），并避免使用分号;，因为它被解释为路径的结束（因为它是配置选项的分隔符）。对于斜杠，您可以用slash选项中定义的任何字符序列替换它（默认为\\）。对于分号，您可以用semicolon选项中定义的任何字符序列替换它（默认为^）。

注意，当设置此选项时，TEXT... 文件可以空，因为其内容将被忽略。并且您不能同时设置 file 和 text 选项。

它必须这样定义：file=PATH，其中

• PATH：要读取的文本文件的路径。它可以以 ~ 开头。

示例

• TEXT;file=|home|myself|texts|intro.txt;slash=| 将使用位于 /home/myself/texts/intro.txt 的文件中的文本。请注意，/ 已由 slash 配置选项定义的 | 替换。
• TEXT;file=\\home\\myself\\texts\\intro.txt 与之前相同，但使用未传递的 slash 配置选项的默认值。

当引用的图像发生变化时，密钥将更新。

如果您不想处理特殊字符，您可以使用 file=__inside__ 并在文件的第一行中写入文本文件的路径。

选项 "slash"

在使用file选项时，在文件名中不可能使用斜杠，因此您可以用slash选项中定义的任何字符或字符序列替换它。如果没有定义，则使用默认值\\。

它必须这样定义：slash=REPLACEMENT，其中

• REPLACEMENT：在command配置选项中用于替换/字符的字符或字符序列。

示例

• TEXT;file=|home|myself|texts|intro.txt;slash=| 将使用位于 /home/myself/texts/intro.txt 的文件中的文本。请注意，/ 已由 slash 配置选项定义的 | 替换。
• TEXT;file=XXXhomeXXXmyselfXXXtextsXXXintro.txt;slash=XXX 与之前相同，但使用 XXX 代替 |
• TEXT;file=\\home\\myself\\texts\\intro.txt 与之前相同，但使用未传递的 slash 配置选项的默认值。

选项 "semicolon"

在使用file选项时，在文件名中不可能使用分号，因此您可以用semicolon选项中定义的任何字符或字符序列替换它。如果没有定义，则使用默认值^。

它必须这样定义：semicolon=REPLACEMENT，其中

• REPLACEMENT：在command配置选项中用于替换;字符的字符或字符序列。

示例

• TEXT;file=\\home\\myself\\texts\\intro^version2.txt 将使用位于 /home/myself/texts/intro;version2.txt 的文件中的文本，使用默认值 / （\\）和 ; （^）。
• TEXT;file=|home|myself|texts|intro,version2.txt;slash=|;semicolon=, 与之前相同，但使用 | 作为斜杠，使用 , 作为分号

选项 "emojis"

此配置选项默认启用，允许将 false 设置为禁用表情符号。主要原因是允许文本在 : 内不被转换为表情符号。

它必须这样定义

• emojis 或 emojis=true 以启用表情符号（默认值）
• emojis=false 以不显示表情符号

示例

• TEXT;text=:joy:、TEXT;text=:joy:;emojis 或 TEXT;text=:joy:;emojis=true 将 :joy: 转换为 😂 表情符号

• TEXT;text=:joy:;emojis=false 将显示 :joy:，而不会将其转换为 😂 表情

配置按键事件（按下、长按、释放、开始、结束）

streamdeckfs 处理来自 StreamDeck 的五个不同事件，如下所示。但首先，让我们看看事件是如何定义的。

一个按键的事件是一个以 ON_ 开头的文件，后面跟着事件名称的大写字母：ON_PRESS、ON_RELEASE、ON_LONGPRESS、ON_START、ON_END。

它配置方式与图像、文本相同，有配置选项，如下所示：ON_PRESS;conf1=value1;conf2=value2

事件是在按键按下、释放等时触发的动作，就像图像一样，它将使用文件本身作为运行的脚本。因此，为了运行特定动作的脚本/程序，请将脚本/程序（或创建到它的链接）复制到 KEY... 目录，并将其重命名为 ON__...。它可以是由操作系统知道的任何可执行文件或带有正确 shebang 的脚本。

每个按键只能有一个每种事件。如果多次定义相同的 ON_XXX，则最新定义的将被使用，其他将被忽略。

如果要在按键按下时执行多个动作，文件可以是包含许多命令、暂停等内容的 bash 脚本。

在事件上可以触发两种其他类型的动作，而不是运行脚本/程序：更改页面（见后面的 page 配置选项）或调整 StreamDeck 的亮度（见后面的 brightness 配置选项）

请注意，当执行命令时，工作目录设置为触发命令的牌/页面/事件。

环境变量

每个命令都是使用 streamdeckfs 启动时接收到的环境变量以及一些其他变量来执行的。

• SDFS_EXECUTABLE：运行 streamdeckfs 的可执行文件（与运行当前 streamdeckfs 实例的可执行文件相同）
• SDFS_DEVICE_TYPE：StreamDeck 模型的类型
• SDFS_DEVICE_SERIAL：当前 StreamDeck 的序列号
• SDFS_DEVICE_DIRECTORY：当前 StreamDeck 的配置目录
• SDFS_DEVICE_NB_ROWS：当前 StreamDeck 的行数
• SDFS_DEVICE_NB_COLS：当前 StreamDeck 的列数
• SDFS_DEVICE_NB_KEYS：当前 StreamDeck 的按键数
• SDFS_DEVICE_KEY_WIDTH：当前 Streamdeck 上按键的宽度，以像素为单位
• SDFS_DEVICE_KEY_HEIGHT：当前 Streamdeck 上按键的高度，以像素为单位
• SDFS_DEVICE_BRIGHTNESS：当前 StreamDeck 的亮度（从 0 到 100 的整数）
• SDFS_VERBOSITY：详尽程度（CRITICAL、ERROR、WARNING、INFO 或 DEBUG 之一）
• SDFS_PAGE：触发事件的页面的编号
• SDFS_PAGE_NAME：触发事件的页面的名称，如果已定义
• SDFS_PAGE_DIRECTORY：触发事件的页面的目录配置
• SDFS_KEY：触发事件的按键（格式 row,col）
• SDFS_KEY_ROW：触发事件的按键的行
• SDFS_KEY_COL：触发事件的按键的列
• SDFS_KEY_NAME：触发事件的按键的名称，如果已定义
• SDFS_KEY_DIRECTORY：触发事件的按键的目录配置
• SDFS_EVENT：触发事件的类型（start、end、press、longpress、release 之一）
• SDFS_EVENT_NAME：触发事件的名称，如果已定义
• SDFS_EVENT_FILE：触发事件的文件配置
• SDFS_QUIET：如果设置了事件的quiet配置选项，则设置为True，否则设置为空字符串
• SDFS_PRESSED_AT：对于按键相关事件（即不是ON_START或ON_END），按键被按下的一瞬间，作为时间戳（带有小数）
• SDFS_PRESS_DURATION：对于按键相关事件（即不是ON_START或ON_END），按键按下与执行命令之间经过的时间，以毫秒为单位（带有小数）

注意，所有变量也将作为环境变量传递。

现在让我们看看不同的事件，然后看看如何配置它们

可用事件

事件“ON_START”

当按键显示时，执行ON_START命令。如果按键停止显示时命令仍在运行（当streamdeckfs结束或更改页面时），则命令将被终止。它可以用来启动一个脚本，该脚本将定期获取一些信息并更新一个按键，例如CPU的温度、当前Spotify歌曲的标题等。

如果命令在按键停止显示时仍然需要运行，它可以“分离”（在这种情况下，即使streamdeckfs结束，它也不会停止）

请注意，如果按键被覆盖层隐藏，如果ON_START命令仍在运行，则不会停止。当覆盖层关闭时，它也不会再次启动。

事件“ON_END”

当按键被隐藏（页面关闭或显示其他页面，但不是覆盖层）时，执行ON_END命令。

请注意，如果按键被覆盖层隐藏，则不会启动ON_END命令。

事件“ON_PRESS”

当按键被按下时（注意，我们有一个不同的“按下”和“释放”事件），执行ON_PRESS命令。在配置选项中，可以运行命令仅当按键按下超过或低于特定时间；如果按下足够长，则可以重复执行等。

与ON_START事件相同，如果命令在按键停止显示时仍在运行，则将被终止，除非设置了“分离”选项。

事件“ON_RELEASE”

ON_RELEASE事件的工作方式类似于ON_PRESS，但动作是在按键按下后释放时触发的。

事件“ON_LONGPRESS”

ON_LONGPRESS事件是在按键按下超过特定时间时触发的事件，默认为300毫秒（0.3秒），但可以进行配置。

可以在同一个按键上定义ON_PRESS和ON_LONGPRESS事件，例如，当按下时执行特定操作，当长按时显示包含更多选项的页面（简单按下播放/暂停Spotify，长按显示Spotify特定页面）。

如果您不想在长按时触发ON_PRESS事件，请将ON_PRESS事件的duration-max配置选项定义为不大于ON_LONGPRESS事件的duration-min。

事件配置选项

除非另有说明，否则所有选项都适用于所有事件。

关于事件配置选项的常见知识

• 所有持续时间都以毫秒为单位。例如，300（它是0.3秒）

选项“wait”

wait选项是事件发生与执行动作之间的延迟。对于ON_PRESS事件，即使按键被释放，也会发生。

它必须定义为这样的格式：delay=DURATION，其中

• 持续时间: 毫秒为单位的持续时间

示例

• ON_START;delay=5000 在键显示后5秒启动由 ON_START 文件定义的动作
• ON_PRESS;delay=300 在按键被按下后0.3秒启动由 ON_PRESS 文件定义的动作

选项 "every"

every 选项允许每隔 XXX 毫秒重复执行动作。

仅适用于 ON_PRESS 和 ON_START 事件。对于 ON_PRESS，重复会在键释放时停止。对于 ON_START，则是在键停止显示时。

必须定义为如下： every=持续时间，其中

• 持续时间: 动作的两次执行之间的延迟，以毫秒为单位

示例

• ON_START;every=5000 将每5秒运行一次由 ON_START 文件定义的动作，只要键被显示
• ON_PRESS;every=500 将每0.5秒运行一次由 ON_PRESS 文件定义的动作，只要键没有被释放

要限制动作重复的次数，请参阅 max-runs 选项。

选项 "max-runs"

max-runs 选项与 every 选项一起使用，并允许设置动作必须重复的最大次数。

必须定义为如下： max-runs=次数，其中

• 次数: 动作可以重复的最大次数

示例

• ON_START;every=5000;max-runs=3 将每5秒运行一次动作，直到键被释放，但最多3次
• ON_PRESS;every=500;max-runs=10 将每0.5秒运行一次动作，直到键被释放，但最多10次

选项 "duration-min"

duration-min 选项指定按键必须按下才能运行 ON_RELEASE 或 ON_LONGPRESS 动作的最小持续时间，这是此选项可用的唯一事件。

必须定义为如下： duration-min=持续时间，其中

• 持续时间: 按键必须按下的最小持续时间，以毫秒为单位，以触发事件。对于 ON_RELEASE 事件，没有默认值，因此默认没有最小持续时间，但对于 ON_LONGPRESS 事件，默认值为300（毫秒）。

在这里，ON_RELEASE 和 ON_LONGPRESS 之间的主要区别是，对于 ON_LONGPRESS，动作将在达到持续时间后立即执行，但对于 ON_RELEASE，只有在达到持续时间后才会在释放键时执行，但它可能远大于这个延迟。

示例

• ON_RELEASE;duration-min=2000: 只有当键至少被按下2秒时才运行动作
• ON_LONGPRESS;duration-min=1000: 在按下键1秒后运行，如果键尚未释放，但不等待键被释放

选项 "duration-max"

duration-max 选项仅适用于 ON_PRESS 事件，并且专门创建用于处理 ON_PRESS 或 ON_LONGPRESS 要执行的事件。

如果未在 ON_PRESS 事件上设置，则即使配置了 ON_LONGPRESS，也会执行 ON_PRESS 事件。为了避免这种情况，必须将 ON_PRESS 键的 duration-max 配置为最多与 ON_LONGPRESS 键的 duration-min（默认为300毫秒）相同。

必须定义为如下： duration-max=持续时间，其中

• 持续时间: 按键必须按下的最大持续时间，以毫秒为单位，以触发事件。

当使用此配置选项时，动作不会在键被按下时直接触发，而是在此延迟之后（或者在键在此延迟之前被释放时）。

示例

• ON_PRESS;duration-max=300 只有在键按下最多300毫秒时才会运行动作。在此延迟后，如果键没有被释放，则不会触发动作。

选项 "detach"

默认情况下，由StreamDeck事件执行的所有命令都与streamdeckfs进程“绑定”。当ON_START事件中的键停止显示或对于其他事件，当streamdeckfs结束时，如果它们仍在运行，则它们会被停止。

通常希望运行一个外部程序，即使streamdeckfs结束，它也应该保持打开。这就是为什么有detach标志。

它必须这样定义

• 使用detach或detach=true来使程序与streamdeckfs进程分离
• 使用detach=false来不使程序分离（当键停止显示或当streamdeckfs结束时）

示例

• ON_PRESS;detach或ON_PRESS;detach=true将使程序分离
• ON_PRESS;detach=false或ON_PRESS将不会使程序分离

选项 "unique"

unique标志可以防止在之前的执行（来自同一事件）尚未完成时运行命令。当与every选项一起使用时，它非常有用，可以在运行下一个之前等待前一个迭代完成。或者对于多次按下。

它必须这样定义

• 使用unique或unique=true来拒绝执行来自同一事件的仍在运行的程序。这是ON_START和ON_END事件的默认行为
• unique=false不会检查程序是否已经在运行，并且这是除了ON_START和ON_END事件之外的默认行为

示例

• ON_PRESS;every=100;detach或ON_PRESS;every=100;detach=true将每100毫秒运行程序一次，但如果前一个执行尚未完成，则将跳过迭代，因此如果程序需要140ms，它将在0ms、200ms、400ms...处运行，而不是在0ms、100ms、200ms...处运行
• ON_PRESS;every=100;detach=false或ON_PRESS;every=100将不会使程序分离，因此它将在0ms、100ms、200ms运行，并且可能同时运行多个相同的程序

选项 "quiet"

quiet标志可以避免在streamdeckfs输出中显示命令的启动（带有PID）和停止（带有返回代码）。当使用every配置选项时非常有用。

它必须这样定义

• 使用quiet或quiet=true来不显示命令的启动和停止
• 使用quiet=false来显示命令的启动和停止。这是默认行为。

示例

• ON_PRESS;every=100;quiet或ON_PRESS;every=100;quiet=true将每100毫秒运行程序一次，但不会显示所有的启动和停止
• ON_PRESS;every=100;quiet=false或ON_PRESS;every=100将显示所有的启动和停止

选项 "command"

默认情况下，事件执行的操作是文件本身的脚本/程序（或它链接到的程序），但这可能不方便。想象一下，如果您想按一下键运行gnome计算器，您必须找到gnome-calculator二进制文件的路径并将其链接到您的ON_PRESS文件，或者使您的ON_PRESS文件成为一个bash脚本，它会调用gnome-calculator。

另一个例子可能是打开默认浏览器中的特定页面。因为有一个参数（要打开的页面），您不能创建一个链接，需要创建这个bash脚本（它并不复杂，但也许您想坚持使用文件名进行整个配置）

command配置选项允许您定义要执行的完整命令，并且它将以这种方式运行。您仍然必须遵守文件名的已知限制（最大长度和没有斜杠/）并避免分号;，因为它被解释为命令的结尾（因为它是配置选项分隔符）。对于斜杠，如果命令中有路径，您可以用slash选项中定义的任何字符序列替换它（默认为\\）。对于分号，您可以用semicolon选项中定义的任何字符序列替换它（默认为^）。

command配置选项可以包含|、>等，就像在控制台中一样。

请注意，当设置此选项时，KEY...文件可以是空的，因为其内容将被忽略。

必须这样定义：command=COMMAND，其中

• COMMAND：要执行的命令

示例

• ON_PRESS;command=gnome-calculator 将运行 gnome 计算器
• ON_PRESS;command=browse https:||elgato.com;slash=| 将在 https://elgato.com 网页上打开默认浏览器。注意，https:// 中的 / 被按照 slash 配置选项定义的 | 替换。
• ON_PRESS;command=browse https:\\\\elgato.com 与上面相同，但在没有传递时使用 slash 配置选项的默认值。

如果您不想处理特殊字符，可以使用 command=__inside__ 并在事件文件中写入命令。文件的全部内容将作为要执行的命令传递。

选项 "slash"

当使用 command 选项时，无法在文件名中使用斜杠，因此您可以将其替换为您使用 slash 选项定义的任何字符或字符组合。如果未定义，则使用默认值 \\。

它必须这样定义：slash=REPLACEMENT，其中

• REPLACEMENT：在command配置选项中用于替换/字符的字符或字符序列。

示例

• ON_PRESS;command=@path@to@myscript | grep foobar > @path@to@log;slash=@ 将运行命令 /path/to/myscript | grep foobar > /path/to/log
• ON_PRESS;command=XXXpathXXXtoXXXmyscript;slash=XXX 将运行命令 /path/to/myscript
• ON_PRESS;command=\\path\\to\\myscript 将使用默认的 slash 值 \\ 运行命令 /path/to/myscript

选项 "semicolon"

当使用 command 选项时，无法在文件名中使用分号，因此您可以将其替换为您使用 semicolon 选项定义的任何字符或字符组合。如果未定义，则使用默认值 ^。

它必须这样定义：semicolon=REPLACEMENT，其中

• REPLACEMENT：在command配置选项中用于替换;字符的字符或字符序列。

示例

• ON_PRESS;command=browse https:\\\\elgato.com^browse https:\\\\github.com 将执行两个操作：在 https://elgato.com 网页上打开默认浏览器，然后打开 https://github.com，使用默认的 slash 和 semicolon 替换值。
• ON_PRESS;command=browse https:XXelgato.com AND browse https:XXgithub.com;slash=X;semicolon= AND 与上面相同，但使用 X 作为 slash 的值和 AND 作为 semicolon 的值。

选项 "亮度"

当按键时，另一种可能的行为是，而不是运行命令，只需更改连接的 StreamDeck 的亮度。

它必须这样定义：brightness=BRIGHTNESS，其中

• BRIGHTNESS：介于 0 和 100（包括两者）之间的值，或一个增量，如 +10 或 -20... 最终值将被限制在可接受范围内。

• ON_PRESS;brightness=+10 将亮度从当前值增加到当前值加 10

• ON_PRESS;brightness=100 将亮度设置为最大值

选项 "页面"

当按键时，另一种可能的行为是转到不同的页面。有关此功能的更多详细信息，请参阅下面的 页面 部分。

它必须这样定义：page=PAGE，其中

• PAGE：要显示的页面的编号或名称（它将使用页面目录名称中的名称：PAGE_NUMBER;name=NAME），或以下特定值之一

  • __first__ 将转到第一个可用的页面编号
  • __previous__ 将转到前一个页面编号（即，实际页面编号减 1）
  • __next__ 将转到下一个页面编号（即，实际页面编号加 1）
  • __back__ 将转到在当前页面之前显示的上一页

有关页面如何工作的更多信息，请参阅下面的 页面 部分。

请注意，此配置选项对 ON_START 和 ON_END 事件不可用。

配置页面事件

与按键一样，页面可以有 start 和 end 事件，通过在页面目录中放置 ON_START 和 ON_END 文件来定义。

当页面显示时，会执行 ON_START 动作。当页面被移除（通过打开新页面（但不是覆盖层），返回上一个页面，或者当 streamdeckfs 被终止时），会执行 ON_END 动作。

上述为按键事件定义的所有可用配置选项，包括 start 和 end 事件，也适用于页面事件，除了 page 和 brightness。

无法在页面事件上设置 变量。

配置牌事件

与页面一样，牌也可以有 start 和 end 事件，这些事件由放置在牌目录中的 ON_START 和 ON_END 文件定义。

当牌启动时，会执行 ON_START 动作。当它停止时，会执行 ON_END 动作。

上述为按键事件定义的，可用于 start 和 end 事件的配置选项，也适用于牌事件，除了 page 和 brightness。

无法在牌事件上设置 变量。

页面

页面是一种扩展 StreamDeck 上可用按键数量的方式，并可以将一些操作分组在一起。

一些示例

• 第一页上的一个按键，简单按下会切换麦克风，长按则显示一个带有增加/减少麦克风灵敏度的按键覆盖层（以及一个关闭覆盖层的按键）

• 第一页上的一个按键，可以打开一个专用于 Spotify 控制的页面

每个页面都是一个目录，至少包含一个页面编号：PAGE_NUMBER，其中 NUMBER 是一个正数。如果两个页面编号相同，则使用最新的目录。

页面还可以有一个名称：PAGE_NUMBER;name=NAME，然后这个名称可用于按键事件的 page 配置。所以如果你有一个名为 PAGE_50;name=spotify 的页面目录，你可以说“转到页面 50”或“转到页面 spotify”。

在页面目录中，你只需要定义需要的按键，而不是所有按键，格式为 KEY_ROW_XX_COL_YY。如果一个按键目录存在但没有图像/文本/事件（或者只有禁用的），则会被忽略。

页面导航历史记录会被保留，这样你可以轻松地返回到之前看到的页面。这对于覆盖层很有帮助。以“麦克风覆盖层”的第一个示例为例。假设你有一个目录 PAGE_60;name=microphone;overlay；你将定义一个带有长按事件的按键来显示这个覆盖层，如下所示：ON_LONGPRESS;page=microphone，在这个 PAGE_60;name=microphone;overlay 目录中，你会有一个按键来关闭这个覆盖层（即返回到上一个页面），如下所示：ON_PRESS;page=__back__。直到你按下这个按键，因为此页面作为覆盖层打开，所以你会看到新页面的按键作为常规按键，而下方的其他按键仍然可见但较暗，按下时没有任何效果。

页面是编号的，但如果没有连续编号的需求，则不必连续编号，例如，如果你想为按键事件使用 page=__next__ 和 page=__previous__ 配置选项，因为它们仅适用于连续页面。

例如，假设你有三个包含经典操作的页面，并想轻松地在它们之间导航，你可以将它们编号为 1、2 和 3。但你也可以有通过某些按键触发的页面，这些页面不应该以这种方式访问，因此编号可以更高。例如 PAGE_50;name=spotify 和 PAGE_60;name=microphone。

在使用页面操作配置时，使用名称非常有用：有page=spotify比page=50更有意义（而且它允许您按需重新组织页面）

run命令将使用页面编号从第一页开始。您可以通过传递页面参数来更改这一点：--page 页面（或-p 页面），其中页面是可用页面的编号或名称。

选项"overlay"

overlay标志允许将页面作为当前页面的覆盖层打开。新页面上的键定义将显示，而对于其他键，将显示当前页面的键，并带有黑色覆盖层以及所有事件都被禁用。这就像网站上的"模态"一样。

它必须这样定义

• overlay或overlay=true将使页面作为覆盖层显示
• overlay=false将使新页面隐藏当前页面，包括未定义的键将变为黑色

示例

• PAGE_50;overlay或PAGE=50;overlay=true将使页面编号50以覆盖层的形式打开
• PAGE_50;overlay=false或PAGE_50将使页面编号50打开，当前页面的任何键都不可见

参考

参考是一种方式，允许键、事件、图像和文本从另一个继承。

假设您有一个专用于Spotify的页面，其中一些键是Spotify控制键，并且应该有相同的背景。

您可以在每个键上有一个名为IMAGE;layer=0;name=background;draw=rectangle;coords=0,0,100%,100%;width=0;fill=#8cc63f的文件

或者，您可以在使用它的第一个键上只定义它，比如说它是KEY_ROW_1_COL_1;name=toggle，在其他键中添加一个名为IMAGE;ref=:toggle:background的文件。这将从当前页面的名为"toggle"的键中获取名为"background"的图像（在ref配置选项中，在第一个:之前没有内容表示"当前页面"）

因此，您可以在一个地方轻松地更改此背景的外观，从而影响所有引用此背景的键。所有配置选项都是继承的。在这个例子中，由IMAGE;ref=:toggle:background定义的图像将继承name、layer、draw、coords、width和fill。但它们可以被覆盖。如果您想更改颜色但仍然有一个矩形，则可以使用IMAGE;ref=toggle:background;fill=red，并将有一个红色矩形作为背景。

关于参考的最后一个重要事项：您可以有参考的参考（的参考，等等）。只是要小心避免循环参考，因为它没有进行检查，streamdeckfs可能会崩溃。

参考配置

可以定义图像层、文本行、事件和键的参考。它们是这样定义的

图片

图像层可以像这样引用另一个图像层：ref=PAGE:KEY:LAYER，其中

• PAGE是包含参考图像的页面的名称或编号，并且没有设置页面（ref=:KEY:LAYER）意味着在定义ref的图像所在的同一页上查找
• KEY是包含参考图像的键的名称或坐标（ROW,COL）
• LAYER是参考图像的名称或层编号，并且没有设置层（ref=PAGE:KEY:）意味着引用没有定义层的KEY上的文本

与所有配置选项一样，如果未指定具有ref选项的图像上的name和layer（如果已定义在参考上），则它们也将被继承。

文本

文本行可以像这样引用另一个文本行：ref=PAGE:KEY:LINE，其中

• PAGE是包含参考文本的页面的名称或编号，并且没有设置页面（ref=:KEY:LINE）意味着在定义ref的图像所在的同一页上查找
• KEY是包含参考文本的键的名称或坐标（ROW,COL）
• LINE 是引用文本的名称或行号，如果没有设置行（ref=PAGE:KEY:），则表示引用没有定义行的 KEY 上的文本。

与所有配置选项一样，如果未在具有 ref 选项的文本上指定，则 name 和 line 也会继承（如果已在引用上定义）。

关键事件

一个关键事件可以像这样引用另一个关键事件：ref=PAGE:KEY:EVENT，其中

• PAGE 是引用事件所在的页面的名称或编号，如果没有设置页面（ref=:KEY:EVENT），则表示在定义 ref 的事件所在页面上查找
• KEY 是引用事件所在键的名称或坐标（ROW,COL）
• EVENT 是引用事件的名称或类型（press、longpress、release、start、end），如果没有设置事件（ref=PAGE:KEY:），则表示引用与 KEY 相同类型的事件。例如，ON_PRESS;ref=PAGE:KEY: 表示在 PAGE 页面的 KEY 键上查找 press 事件

页面事件

一个页面事件可以像这样引用另一个页面事件：ref=PAGE:EVENT，其中

• PAGE 是引用事件所在的页面的名称或编号，如果没有设置页面（ref=:EVENT），则表示在定义 ref 的事件所在页面上查找
• EVENT 是引用事件的名称或类型（start、end），如果没有设置事件（ref=PAGE:），则表示引用与 PAGE 相同类型的事件。例如，ON_START;ref=PAGE: 表示在 PAGE 页面上查找 start 事件

按键

一个按键可以像这样引用另一个按键：ref=PAGE:KEY，其中

• PAGE 是引用键所在的页面的名称或编号，如果没有设置页面（ref=:KEY），则表示在定义 ref 的事件所在页面上查找
• KEY 是引用键的名称或坐标（ROW,COL），如果没有设置键（ref=PAGE:），则表示引用与 PAGE 相同坐标的按键

按键引用是特定的，因为一个按键可以包含文本、图像、事件等。其工作方式很简单：默认情况下，引用键中可用的所有内容都会“导入”到引用它的键中，但在引用它的目录键中，您可以添加文本、图像、事件等，这将“替换”引用键中的内容。因此，您可以添加层、文本，如果需要更改图像的某个配置，则可以引用它并仅添加要更新的配置。以下是在使用“关闭”引用时的示例。

部分配置更新

在前面几节中描述 margin、crop、coords 和 angles 时，我们看到了例如可以定义 margin.1，但当时似乎没有用处。现在，有了引用和覆盖此功能的强大功能，其可见性就显现出来了：您可以在引用上定义完整选项，并仅更新在定义引用的对象上需要更新的部分。

例如，您有多个需要不同长度的“进度条”的键。您可以像这样定义您的引用层：IMAGE;name=progress;draw=line;coords=0,92,0,92;outline=white;width=7。您可以看到 coords 配置选项的第三个是 0。这是线的 X2 坐标，即它结束的地方。当您需要引用它时，您只需设置 coords.2（2 表示第三个部分，因为索引从 0 开始）：IMAGE;ref=page:key:progress;coords.2=50%。现在您有一条宽度为按键宽度 50% 的线。

对于 crop 和 margin，你可以使用 .left、.right、.top 和 .bottom 而不是位置属性。

用法示例：参考页面

在许多可能的参考应用中，一种使用方法是创建一个“参考”页面，将你的配置中共同的东西放入该页面。

以下是一个这样的页面示例

└── PAGE_999;name=ref
    ├── KEY_ROW_1_COL_1;name=img
    │   └── IMAGE;layer=999;name=overlay -> /home/twidi/dev/streamdeck-scripts/assets/overlay.png
    ├── KEY_ROW_1_COL_2;name=draw
    │   ├── IMAGE;layer=0;name=background;draw=fill;fill=
    │   └── IMAGE;name=progress;draw=line;coords=0%,92,32%,92;outline=white;width=7
    ├── KEY_ROW_2_COL_1;name=close
    │   ├── IMAGE;layer=1;colorize=white;margin=20,10,10,10;name=icon -> /home/twidi/dev/streamdeck-scripts/assets/close.png
    │   ├── IMAGE;ref=:images:overlay
    │   └── ON_PRESS;page=__back__
    └── KEY_ROW_2_COL_2;name=titled-text
        ├── IMAGE;layer=1;name=separator;draw=line;coords=0,25,100%,25;outline=
        ├── TEXT;line=1;name=title;text=Title;weight=bold;align=center;valign=top;color=
        └── TEXT;line=2;name=content;text=Some content that will scroll if too long;size=18;align=center;valign=middle;margin=28,0,0,0;scroll=20;wrap

在这里你可以看到一个页面，编号为999（可以是任何编号）名称为ref。

在这个页面上，定义了许多键

• KEY_ROW_1_COL_1;name=img

这个键包含一个具有层编号999、名称为"overlay"的图像。目标是每个定义的键都覆盖一个具有特定样式（如“玻璃”渲染）的叠加层。由于层编号为999，它几乎肯定将是顶层。要使用它，在你的KEY...目录中添加一个空文件，命名为IMAGE;ref=ref:img:overlay。

• KEY_ROW_2_COL_2;name=draw

这个键包含两个绘图

一个名为background（其中仅缺少填充颜色），可以像这样引用：IMAGE;ref=ref:draw:background;fill=ref

一个名为progress的绘图在键的底部绘制一个进度条（其中X2坐标必须更新为适当的进度值（在这里是32%）），可以像这样引用：IMAGE;layer=3;ref=ref:draw:progress;coords.2=50%（在这里我们将进度更改为50%并将层编号设置为3，因为引用没有定义，因为每个使用它的键可能希望将progress放置在不同的层）

• KEY_ROW_2_COL_1;name=close

这个键代表一个完整的“关闭”键，可以在按下时关闭叠加层。要使用它，在你的页面上添加一个名为KEY_ROW_X_COL_Y;ref=ref:close的目录（根据需要设置你的行和列）： voila，你就有了一个按预期工作的关闭键。

如果你想改变关闭键的颜色，在你的目录中添加一个引用icon的图像：IMAGE;ref=ref:close:icon;colorize=red。它将继承参考键中图像的相同层编号，并将替换那个图像。

• KEY_ROW_2_COL_2;name=titled-text

这个键代表一个带有顶部标题、小分隔线和中央区域的文本的键，该文本被包装并且如果不适合则会滚动。这个键本身不是用作参考的，因为每个部分都必须进行配置，所以你像平常一样定义你的键目录，并在其中添加三个空文件IMAGE;ref=ref:titled-text:separator;outline=COLOR（其中COLOR是你想要的分隔线颜色），TEXT;ref=ref:titled-text:title;text=TITLE（其中TITLE是你想要的标题文本）和TEXT;ref=ref:titled-text:content;text=TEXT（其中TEXT是你想要的中央区域文本，或者你可以设置file=__self__代替text=...并将文本放在文件中）

变量

streamdeckfs可以用作存储由其事件启动的命令的存储库。为此，它使用可以在牌组、页面或键目录中的文件，这些文件命名为VAR_NAME，其中NAME是你选择的一个名称（它只能包含从A到Z的大写字母、从0到9的数字和字符_）。

对于其他类型的对象，可以通过添加;disabled（或;disabled=true，见上面，或;enabled=false）来禁用。

变量的值将从文件本身读取，或从文件名中的value配置选项读取。例如，文件VAR_FOO;value=bar定义了一个值为bar的变量FOO。当从value配置选项读取时，如果你想要分号;或斜杠/，你必须使用^或\\（或者通过分号和斜杠配置选项指定要使用的字符（如文本/图像中的路径file和事件command选项））。

注意，要从其他文件读取值，也可以使用为TEXT*文件定义的file配置选项。

当获取变量的值时，我们使用“级联”：如果变量在请求的目录中没有定义，它将在父目录中查找（对于关键变量是页面，然后是牌组，对于页面变量是牌组）。这允许在较高级别有一个“默认值”，在较低级别被覆盖。

变量可以用于页面、键、图像、文本...的文件名以及变量本身，在需要时将被替换。

假设你有一个包含空文件VAR_FOO;value=bar或包含bar的文件VAR_FOO的键目录。然后你可以有一个文本文件TEXT;text=$VAR_FOO，文本bar将被显示。级联被尊重：如果VAR文件在键目录中找不到，它将在页面目录或牌组目录中查找。

在streamdeckfs运行时可以创建、更新或删除变量，并且这些更新将如预期的那样反映出来（在上面的示例中，如果你将VAR_FOO;value=bar重命名为VAR_FOO;value=BAR，键将自动更新以显示BAR）。

如果文件名包含无法找到的变量，则该文件将直到变量文件可用为止被忽略。

当事件（例如按键）触发命令时，所有可用于此事件的变量都将作为环境变量传递（前缀为SDFS_，因此在我们的示例中我们将有SDFS_VAR_FOO，包含值BAR）。

位置

变量可以

• 用于文件/目录名，并且不仅限于选项配置的值，因为配置解析将在替换变量之后进行。因此，TEXT;$VAR_TEXT_STYLE是可能的，例如VAR_TEXT_STYLE;value=color=red^fit^wrap（这里使用默认的分号替换，但如果值在VAR_TEXT_STYLE文件的内容中，可以使用真实的;字符）。

• 在value配置选项的变量中，因为变量可以依赖于另一个变量（只要没有循环依赖）。

• 在TEXT或VAR文件的内容中。

• 在配置为file=__inside__的TEXT、IMAGE或VAR文件的内容中定义的路径中，或者在配置为command=__inside__的ON_（事件）文件中。

• 在"等于"规则的右侧（引号之间的部分）。

请注意，变量可以由其他变量组成：text=$VAR_$VAR_DISPLAY将工作，因为第一个$VAR_不是一个有效的变量，但$VAR_DISPLAY是，所以，$VAR_DISPLAY将被转换为，例如，如果VAR_DISPLAY;value=LASTNAME，则转换为LASTNAME，所以我们有text=$VAR_LASTNAME，然后读取VAR_LASTNAME变量以获得最终文本。同样，在text=$VAR_TEXT$VAR_INDEX中，如果VAR_TEXT不是一个存在的变量，则在第一次遍历中$VAR_INDEX将被转换为，例如，转换为1，然后我们有$VAR_TEXT1，它是一个存在的变量，所以它的被转换。

行索引

如果变量 VAR_ 的值是由其内容定义的（即，不是使用 value=），并且其内容在多行上，则可以通过使用 $VAR_FOO[INDEX] 访问特定行，其中 INDEX 是要访问的行号，从 0 开始。还可以使用反向索引（-1 是最后一行，-2 是倒数第二行……）。

要获取行数，可以使用 [#]。

例如，如果文件 VAR_FOO 包含

foo
bar
baz

则会有

• $VAR_FOO[0] => foo
• $VAR_FOO[1] => bar
• $VAR_FOO[2] => baz
• $VAR_FOO[-1] => baz
• $VAR_FOO[-2] => bar
• $VAR_FOO[-3] => foo
• $VAR_FOO[#] => 3

使用环境变量

可以使用 streamdeckfs 定义的 环境变量 作为变量，例如，使用 $VAR_SDFS_PAGE 来获取 SDFS_PAGE 环境变量的值，即当前页码。因此，无法创建以 $VAR_SDFS_ 开头的变量。

注意，与事件相关的环境变量（SDFS_EVENT* 和 SDFS_PRESS*）不能使用。

条件语句

在定义变量时（而不是使用它时），可以使用 if/then/else 来设置其值。

所有这些都是配置选项，需要在文件名中设置，例如 VAR_FOO;if=CONDITION;then=VALUE_IF;else=?VALUE_ELSE;，其中

• CONDITION：要检查的条件。必须是 true 或 false（不区分大小写），并且可以与变量组合（因为直接设置 if=true 没有意义）。例如 if=$VAR_FOO="bar"
• VALUE_IF：如果 CONDITION 为 true，则将使用此值
• VALUE_ELSE：如果 CONDITION 为 false，则将使用此值

此外，还可以使用额外的 elif + else 组，例如 VAR_FOO;if=CONDITION1;then=VALUE_IF1;elif=CONDITION2;then=VALUE_IF2;elif=CONDITION3;then=VALUE_IF3;else=VALUE_ELSE;

下面将展示如何使用示例。

表达式

值可以是某些表达式的结果。例如，{100/3}% 将给出 33.3333%。

表达式用 { 和 } 包围，并且所有通过 py-expression-eval 库实现的功能都可以使用（我们在 streamdeckfs 包中包含了一个分支，略作修改的此库版本）。

一些示例

• disabled={"$VAR_FOO" == "foo"} 将在 VAR_FOO 的值为 foo 时将禁用设置为 true。此示例表明，包含字符串的变量必须用双引号括起来，因为首先会替换所有变量的确切内容，然后才会计算表达式。

• VAR_NEXT_INDEX;if={$VAR_INDEX==$VAR_TEXTS[#]-1};then=0;else={$VAR_INDEX+1} 将在 $VAR_NEXT_INDEX 中设置用于在包含多行的 VAR_TEXTs 文件中使用的下一行，除了当我们处于最后一行时（if={$VAR_INDEX==$VAR_TEXTS[#]-1}），在这种情况下，我们回到 0

查看 py-expression-eval 库页面，以了解可以做什么。我们使用的版本与原始版本有两个不同之处

• 你必须使用 | 而不是 / 进行除法，因为 / 不能用于文件名
• 我们添加了整除，使用 ||（如果不在文件名中使用，则 // 可用）
• 我们添加了 int() 和 float() 函数
• 我们添加了 str() 函数
• 我们删除了 concat() 函数（使用 || 进行整除，并且除以 str() 之外，还可以使用 + 来模拟 concat()）
• 我们添加了 True 和 False 值
• 我们添加了format()函数：format(value, "FORMAT")，其中FORMAT是在使用普通format函数（不包含{和}）时冒号后面的部分。例如，format(7, "02")将输出07。

表达式不仅从文件名中评估，还评估在变量文件的内容中。

它们在所有包含的变量被替换后评估，并且每次变量更新时都会更新。

设置变量的关键事件

除了对之前描述过的按键事件的操作之外，即page、brightness和command，还可以设置一个或多个变量的值（同时执行其他操作）

要使事件设置变量，必须像这样定义：VAR_NAME=VALUE，其中

• VAR_NAME：要设置的变量（以VAR_开头）
• VALUE：此变量的新值（可以是固定值、另一个变量（使用$VAR_...）或表达式）

为每个要设置的变量重复。

如果变量文件不存在，则将其创建，否则将其更新（如果存在，则移除其disabled或enabled属性）

默认情况下，变量将在按键的目录中创建/更新。但可以将其放在其他位置

• :VAR_NAME将其放在包含按键的页面的目录中
• ::VAR_NAME将其放在牌堆的目录中
• :KEY:VAR_NAME将其放在当前按键所在页面中另一个按键（通过名称或通过row,col格式）的目录中
• ::PAGE:KEY:VAR_NAME将其放在另一页中另一个按键的目录中（通过名称或编号定义）
• ::PAGE:VAR_NAME将其放在另一页的目录中

值将设置在变量VAR_NAME;value=VALUE的名称（在value配置选项中）上。

但也可以通过在变量名称后附加<来将其设置为文件的内容：VAR_NAME<=VALUE。在这种情况下，变量的文件名将是VAR_NAME，其内容将是VALUE。您可以通过将<=操作符视为一个箭头来记住，它表示我们将VALUE放入VAR_NAME中。

例如，将名为FOO的变量设置为在名为mypage的页面上按下键时的值bar

ON_PRESS;::mypage:VAR_FOO<=bar

示例

示例 1

下面的第一个示例显示了如何根据状态显示不同的文本。此示例还将显示如何使用“表达式”（用{和}括起来，并通过VAR_STATE=value=state_$VAR_STATE_VALUE显示变量值可以使用变量本身，并且变量不需要是配置选项的全值

TEXT;text=1;fit;enabled={"$VAR_STATE" == "state_one"}
TEXT;text=2;fit;enabled={"$VAR_STATE" == "state_two"}
TEXT;text=3;fit;enabled={"$VAR_STATE" == "state_three"}
VAR_STATE;value=state_$VAR_STATE_VALUE
VAR_STATE_VALUE;value=one

此示例将显示1，这是VAR_STATE_VALUE的当前值（one）。

示例 2

下面的第二个示例显示了如何在一个配置选项中同时使用变量（VAR_TEXT_STYLE），以及如何将变量设置在文件内容中。

文件如下

TEXT;$VAR_TEXT_STYLE
VAR_FULLNAME
VAR_FIRSTNAME
VAR_LASTNAME
VAR_TEXT_STYLE

和它们的内容

• TEXT;$VAR_TEXT_STYLE:

Hello
$VAR_FULLNAME!

• VAR_FULLNAME

$VAR_FIRSTNAME $VAR_LASTNAME

• VAR_FIRSTNAME

Foo

• VAR_LASTNAME

Bar

• VAR_TEXT_STYLE

color=red;fit;wrap

这将在按键上以红色显示文本“Hello Foo Bar”。

示例 3

下面的第三个示例显示了如何在路径中使用变量。我们想根据变量更改显示的图标。

我们有两个文件

• 一个名为IMAGE;colorize=white;file=__inside__的图像文件，其中包含/path/to/icons/$VAR_ICON.png
• 一个名为VAR_ICON的变量文件，包含thumbs-up

然后事件或外部脚本可以更改VAR_ICON文件的内容来更新按键。

示例 4

下面的第四个示例显示了如何交替显示3个表情符号。

我们利用了这样一个事实：我们可以多次定义相同的事件（这里为 ON_PRESS），但禁用的事件会被忽略。因此，我们只保留一个启用的事件。事件的动作是将下一个表情符号设置到变量中，该变量用于在键上显示表情符号，并且知道要禁用哪些事件。

所以我们有

• 如下定义的文本：TEXT;fit;text=$VAR_EMOJI
• 如下定义的变量文件：VAR_EMOJI;value=:joy:
• 以及三个 ON_PRESS，根据表情符号的不同，只有一个会被激活，用于显示下一个表情符号
  • ON_PRESS;VAR_EMOJI=:joy:;enabled={"$VAR_EMOJI" == ":sob:"}
  • ON_PRESS;VAR_EMOJI=:neutral_face:;enabled={"$VAR_EMOJI" == ":joy:"}
  • ON_PRESS;VAR_EMOJI=:sob:;enabled={"$VAR_EMOJI" == ":neutral_face:"}

如果不希望将表情符号硬编码到多个文件中，可以采用另一种方式编写此示例

• 与上述相同的文本：TEXT;fit;text=$VAR_EMOJI
• 如下定义的变量文件：VAR_EMOJI;value=$VAR_EMOJI1
• 定义了三个表情符号变量，这样我们可以在不改变其他任何内容的情况下更改它们
  • VAR_EMOJI1;value=:joy
  • VAR_EMOJI2;value=:neutral_face
  • VAR_EMOJI3;value=:sob
• 以及我们的三个 ON_PRESS
  • ON_PRESS;VAR_EMOJI=$VAR_EMOJI1;enabled={"$VAR_EMOJI" == "$VAR_EMOJI3"}
  • ON_PRESS;VAR_EMOJI=$VAR_EMOJI2;enabled={"$VAR_EMOJI" == "$VAR_EMOJI1"}
  • ON_PRESS;VAR_EMOJI=$VAR_EMOJI3;enabled={"$VAR_EMOJI" == "$VAR_EMOJI2"}

甚至可以使其更通用

• 如下定义的文本：TEXT;fit;text=$VAR_TEXT$VAR_INDEX

• 如下定义的变量文件：VAR_INDEX;value=1

• 定义了三个文本变量，这样我们可以在不改变其他任何内容的情况下更改它们

  • VAR_TEXT1;value=:joy
  • VAR_TEXT2;value=:neutral_face
  • VAR_TEXT3;value=:sob

• 以及三个 ON_PRESS，根据索引的不同，只有一个会被激活，用于显示下一个文本

  • ON_PRESS;VAR_INDEX=1;enabled={$VAR_INDEX == 3}
  • ON_PRESS;VAR_INDEX=2;enabled={$VAR_INDEX == 1}
  • ON_PRESS;VAR_INDEX=3;enabled={$VAR_INDEX == 2}

  其中的魔法在于 TEXT;fit;text=$VAR_TEXT$VAR_INDEX，因为 $VAR_TEXT 不是一个现有的变量，但 $VAR_INDEX 是，因此首先将 $VAR_INDEX 转换为 1，然后我们就有了一个可以转换的 $VAR_TEXT1。

我们也可以使用条件语句来减少文件数量：

• 我们仍然有我们的文本：TEXT;fit;text=$VAR_TEXT$VAR_INDEX
• 以及我们的索引变量：VAR_INDEX;value=1
• 我们的文本变量
  • VAR_TEXT1;value=:joy
  • VAR_TEXT2;value=:neutral_face
  • VAR_TEXT3;value=:sob

但是，我们不再使用3个 ON_PRESS 来设置下一个索引，而是创建一个 VAR_NEXT_INDEX 变量

• VAR_NEXT_INDEX;if={$VAR_INDEX==1};then=2;elif={$VAR_INDEX==2};then=3;else=1

最后是我们的单个 ON_PRESS 文件

• ON_PRESS;VAR_INDEX=$VAR_NEXT_INDEX

使用行索引，我们可以减少文件数量

• 我们仍然有我们的文本，但使用索引：TEXT;fit;text=$VAR_TEXTS[$VAR_INDEX]
• 以及我们的索引变量：VAR_INDEX;value=1
• 以及我们的 ON_PRESS 文件：ON_PRESS;VAR_INDEX=$VAR_NEXT_INDEX
• 但现在我们只有一个包含三个行的 VAR_TEXTS 文件

:joy:
:neutral_face:
:sob:

• 我们的 $VAR_NEXT_INDEX 已经更新，以考虑到行从0开始

• VAR_NEXT_INDEX;if={$VAR_INDEX==0};then=1;elif={$VAR_INDEX==1};then=2;else=0

最后，为了使它无论 VAR_TEXTS 中有多少行都能工作，我们可以使用操作

• VAR_NEXT_INDEX;if={$VAR_INDEX==$VAR_TEXTS[#]-1};then=0;else={$VAR_INDEX+1}

API

由于所有操作都在文件名中完成（除了有时是文本/图像/变量），因此更新一个键非常容易：只需重命名文件以更改其配置选项。StreamDeck 将在近实时更新。这可以手动完成，也可以编程完成。

但是，如果您编程方式完成，您需要知道文件的准确路径和名称...这将在您重命名它时发生变化，因此您必须保留该名称。

streamdeckfs 提供一组命令作为API，以避免手动执行，允许执行诸如“禁用名为foobar的mykey键在mypage页面上的层”或“将此行的右坐标移动到90%”的操作（现在你可以看到为什么像“coords.2”这样的东西很有用）。你甚至可以完全使用这个API来创建一切。

请注意，在使用以下API命令之前，你必须至少成功运行一次make-dirs或run命令。这是必要的，因为API不与StreamDeck连接（它只接触文件），需要存储有关StreamDeck的信息。

使用这些命令，你可以对一个页面、键、文本、图像、事件或变量进行以下操作：

• 列出它们
• 获取其路径
• 获取其配置选项作为JSON
• 更新一个或多个配置选项
• 复制它
• 移动它
• 删除它
• 创建一个

所有这些配置命令的调用方式相同

streamdeckfs COMMAND SERIAL_DIRECTORY ARGUMENTS

对于所有这些配置命令，SERIAL_DIRECTORY是以你想要更新配置的StreamDeck的序列号结尾的目录。不会连接到StreamDeck，因为这些配置命令所做的唯一事情是读取这个目录下的目录和文件，提取配置，并返回你所请求的内容，或者根据要求创建或重命名文件。

get-deck-info

将打印一些有关StreamDeck的信息（以JSON格式）。只有当已经为StreamDeck/目录调用过一次make-dirs或run时，此命令才会生效。

streamdeckfs get-deck-conf SERIAL_DIRECTORY

示例

$ streamdeckfs get-deck-info ~/streamdeck-data/MYDECKSERIAL
{'model': 'StreamDeckXL', 'nb_rows': 4, 'nb_cols': 8, 'key_width': 96, 'key_height': 96}

get-brightness

将打印当前的亮度（一个介于0到100的整数）。

streamdeckfs get-brightness SERIAL_DIRECTORY

示例

$ streamdeckfs get-brightness ~/streamdeck-data/MYDECKSERIAL
30

set-brightness

将更新亮度。

streamdeckfs set-brightness SERIAL_DIRECTORY -b BRIGHTNESS

使用以下参数：

• BRIGHTNESS：所需的亮度，作为一个介于0到100的整数（包括0和100）

示例

$ streamdeckfs set-brightness ~/streamdeck-data/MYDECKSERIAL -b 50

get-current-page

将打印一些有关当前页面（如果有的话）的信息。

streamdeckfs get-current-page SERIAL_DIRECTORY

示例

$ streamdeckfs get-current-page ~/streamdeck-data/MYDECKSERIAL
{"number": 60, "name": "spotify", "is_overlay": false}

set-current-page

将请求的页面设置为活动页面。

streamdeckfs set-current-page SERIAL_DIRECTORY PAGE

使用以下参数：

• PAGE：要请求的页面的数字或名称，或以下之一：
  • __first__：转到第一个可用的页面编号
  • __previous__：转到前一个页面编号（即，当前页面编号减1）
  • __next__：转到下一个页面编号（即，当前页面编号加1）
  • __back__：转到当前页面之前显示的上一页

示例：打开spotify页面

$ streamdeckfs set-current-page ~/streamdeck-data/MYDECKSERIAL -p spotify

示例：返回到上一页

$ streamdeckfs set-current-page ~/streamdeck-data/MYDECKSERIAL -p __back__

请注意，如果在此命令执行时streamdeckfs未运行，则将在下一次运行时打开所需的页面。

list-pages

将打印牌的页面。

streamdeckfs list-pages SERIAL_DIRECTORY DISABLED

使用以下参数：

• DISABLED：可以是--without-disabled（默认值，仅列出可渲染的页面）或--with-disabled（列出所有页面）

页面按每行一个列出，对于每个页面，其结果与调用get-page-conf时的结果相同。有关输出示例，请参阅get-page-conf。

get-page-path

将打印所请求页面的完整路径。

streamdeckfs get-page-path SERIAL_DIRECTORY -p PAGE

使用以下参数：

• PAGE：要请求的页面的数字或名称

示例

$ streamdeckfs get-page-path ~/streamdeck-data/MYDECKSERIAL -p spotify
/home/twidi/streamdeck-data/MYDECKSERIAL/PAGE_60;name=spotify

get-page-conf

将打印所请求页面的完整配置（包括从引用继承的选项）的JSON表示。

streamdeckfs get-page-conf SERIAL_DIRECTORY -p PAGE

使用以下参数：

• PAGE：要请求的页面的数字或名称

示例

$ streamdeckfs get-page-conf ~/streamdeck-data/MYDECKSERIAL -p spotify
{"kind": "PAGE", "page": "60", "name": "spotify"}

set-page-conf

将更新所请求页面的配置。

streamdeckfs get-page-conf SERIAL_DIRECTORY -p PAGE -c OPTION1 VALUE1 -c OPTION2 VALUE2

使用以下参数：

• PAGE：要请求的页面的数字或名称
• OPTION：要更新的一个选项
• VALUE：该选项的值

你可以有多个-c OPTION VALUE部分来更新多个配置选项。要删除配置选项，将VALUE传递为一个空字符串。

此命令返回页面的更新路径。使用--dry-run以获取此路径而不实际进行更改（也可以用于验证参数）。

示例：更改页面名称并禁用它

$ streamdeckfs set-page-conf ~/streamdeck-data/MYDECKSERIAL -p spotify -c name spotify2 -c disabled true

create-page

将创建一个新的页面。

streamdeckfs create-page SERIAL_DIRECTORY -p NUMBER -c OPTION1 VALUE1 -c OPTION2 VALUE2

使用以下参数：

• NUMBER：要创建的页面编号，或用于查找可用页面编号的表达式。此参数为可选参数：不传递它（或传递空字符串）相当于传递“0+”表达式，即使用第一个可用的页面编号。可能的表达式有

  • NUMBER+：获取 NUMBER 之后的第一页
  • NUMBER+NUMBER：获取这两个数字之间（不包括这两个数字）的第一页
  • ?：获取一个随机的可用页面编号
  • NUMBER?：获取一个大于 NUMBER 的随机可用页面编号
  • ?NUMBER：获取一个小于 NUMBER 的随机可用页面编号
  • NUMBER?NUMBER：获取这两个数字之间（不包括这两个数字）的一个随机可用页面编号

  如果找不到匹配表达式的可用页面，将引发错误。注意：将在 0 到 100000 之间搜索可用页面编号。

• OPTION：一个设置选项

• VALUE：该选项的值

您可以有多个 -c OPTION VALUE 部分来设置多个配置选项。

此命令返回新创建页面的完整路径。使用 --dry-run 可获取此路径而无需实际执行更改（也可用于验证参数）。

例如，要创建编号为 20 的页面，名称为 foo

$ streamdeckfs create-page ~/streamdeck-data/MYDECKSERIAL -p 20 -c name foo
/home/twidi/streamdeck-data/MYDECKSERIAL/PAGE_20;name=foo

或者创建它在一个介于 49 和 60（两者都不包括）之间的可用页面上

$ streamdeckfs create-page ~/streamdeck-data/MYDECKSERIAL -p '49?60' -c name foo
/home/twidi/streamdeck-data/MYDECKSERIAL/PAGE_53;name=foo

copy-page

将制作页面的完整副本（包括其键和所有图像、文本、事件）

streamdeckfs copy-page SERIAL_DIRECTORY -p PAGE -tp NUMBER -c OPTION1 VALUE1 -c OPTION2 VALUE2

使用以下参数：

• PAGE：要复制的页面的编号或名称

• NUMBER：新页面的编号（-tp 用于 --to-page），或用于查找可用页面编号的表达式。此参数为可选参数：不传递它（或传递空字符串）相当于传递“0+”表达式，即使用第一个可用的页面编号。可能的表达式有

  • NUMBER+：获取 NUMBER 之后的第一页
  • NUMBER+NUMBER：获取这两个数字之间（不包括这两个数字）的第一页
  • ?：获取一个随机的可用页面编号
  • NUMBER?：获取一个大于 NUMBER 的随机可用页面编号
  • ?NUMBER：获取一个小于 NUMBER 的随机可用页面编号
  • NUMBER?NUMBER：获取这两个数字之间（不包括这两个数字）的一个随机可用页面编号

  如果找不到匹配表达式的可用页面，将引发错误。注意：将在 0 到 100000 之间搜索可用页面编号。

• OPTION：要更新的一个选项

• VALUE：该选项的值

您可以有多个 -c OPTION VALUE 部分来设置多个配置选项。建议设置一个与源页面不同的名称。

此命令返回新创建页面的完整路径。使用 --dry-run 可获取此路径而无需实际执行更改（也可用于验证参数）。

例如，创建编号为 20 的页面副本，名称为 foo，并创建一个新页面，编号为 30，名称为 bar

$ streamdeckfs copy-page ~/streamdeck-data/MYDECKSERIAL -p 20 -tp 30 -c name bar
/home/twidi/streamdeck-data/MYDECKSERIAL/PAGE_30;name=bar

move-page

将页面移动到不同的编号

streamdeckfs move-page SERIAL_DIRECTORY -p PAGE -tp NUMBER -c OPTION1 VALUE1 -c OPTION2 VALUE2

使用以下参数：

• PAGE：要移动的页面的编号或名称

• NUMBER：新页面的编号（-tp 用于 --to-page），或用于查找可用页面编号的表达式。此参数为可选参数：不传递它（或传递空字符串）相当于传递“0+”表达式，即使用第一个可用的页面编号。可能的表达式有

  • NUMBER+：获取 NUMBER 之后的第一页
  • NUMBER+NUMBER：获取这两个数字之间（不包括这两个数字）的第一页
  • ?：获取一个随机的可用页面编号
  • NUMBER?：获取一个大于 NUMBER 的随机可用页面编号
  • ?NUMBER：获取一个小于 NUMBER 的随机可用页面编号
  • NUMBER?NUMBER：获取这两个数字之间（不包括这两个数字）的一个随机可用页面编号

  如果找不到匹配表达式的可用页面，将引发错误。注意：将在 0 到 100000 之间搜索可用页面编号。

• OPTION：要更新的一个选项

• VALUE：该选项的值

您可以有多个 -c OPTION VALUE 部分来设置多个配置选项。

此命令返回移动页面的完整新路径。使用 --dry-run 可获取此路径而无需实际执行更改（也可用于验证参数）。

例如，将名称为 foo 的页面 20 移动到编号为 30，名称为 bar

$ streamdeckfs move-page ~/streamdeck-data/MYDECKSERIAL -p 20 -tp 30 -c name bar
/home/twidi/streamdeck-data/MYDECKSERIAL/PAGE_30;name=bar

delete-page

将删除请求的页面目录。

streamdeckfs delete-page SERIAL_DIRECTORY -p PAGE

使用以下参数：

• PAGE：要删除的页面的编号或名称

此命令返回删除的页面目录的路径。使用 --dry-run 可获取此路径而无需实际执行更改（也可用于验证参数）。

示例

$ streamdeckfs delete-page ~/streamdeck-data/MYDECKSERIAL -p spotify

list-keys

将打印页面的键。

streamdeckfs list-keys SERIAL_DIRECTORY -p PAGE DISABLED

使用以下参数：

• PAGE：要列出键的页面的编号或名称
• DISABLED：要么 --without-disabled（默认值，只列出可渲染的键）要么 --with-disabled（列出所有键）

键按行列出，每行对应的输出结果与调用 get-key-conf 相同。有关输出示例，请参阅 get-key-conf。

get-key-path

将打印请求的键的完整路径。

streamdeckfs get-key-path SERIAL_DIRECTORY -p PAGE -k KEY

使用以下参数：

• PAGE：要在其中找到所需键的页面的编号或名称
• KEY：键的名称或其“位置”（例如 ROW,COL，例如 1,2 表示第一行的第二个键）

示例

$ streamdeckfs get-key-path ~/streamdeck-data/MYDECKSERIAL -p spotify -k progress
/home/twidi/streamdeck-data/MYDECKSERIAL/PAGE_60;name=spotify/KEY_ROW_2_COL_4;name=progress

get-key-conf

将打印请求的键的完整配置的 JSON 表示（包括从引用继承的选项）。

streamdeckfs get-key-conf SERIAL_DIRECTORY -p PAGE -k KEY

使用以下参数：

• PAGE：要在其中找到所需键的页面的编号或名称
• KEY：键的名称或其“位置”（例如 ROW,COL，例如 1,2 表示第一行的第二个键）

示例

$ streamdeckfs get-key-conf ~/streamdeck-data/MYDECKSERIAL -p spotify -k progress
{"kind": "KEY", "row": "2", "col": "4", "name": "progress"}

set-key-conf

将更新请求的键的配置。

streamdeckfs set-key-conf SERIAL_DIRECTORY -p PAGE -k KEY -c OPTION1 VALUE1 -c OPTION2 VALUE2

使用以下参数：

• PAGE：要在其中找到所需键的页面的编号或名称
• KEY：键的名称或其“位置”（例如 ROW,COL，例如 1,2 表示第一行的第二个键）
• OPTION：要更新的一个选项
• VALUE：该选项的值

你可以有多个-c OPTION VALUE部分来更新多个配置选项。要删除配置选项，将VALUE传递为一个空字符串。

此命令返回键的更新路径。使用 --dry-run 可获取此路径而不实际进行更改（也可用于验证参数）。

示例，禁用键

$ streamdeckfs set-key-conf ~/streamdeck-data/MYDECKSERIAL -p spotify -k progress -c disabled true

create-key

将创建一个新的键。

streamdeckfs create-key SERIAL_DIRECTORY -p PAGE -k ROW,COL -c OPTION1 VALUE1 -c OPTION2 VALUE2

使用以下参数：

• PAGE：要创建所需键的页码或名称

• ROW,COL：新键的位置，或查找可用键的表达式。此参数为可选：不传递（或传递空字符串）相当于传递 "+" 表达式。可能的表达式包括

  • +：获取第一个可用的键（按行顺序）
  • ?：获取一个随机可用的键

  如果找不到匹配表达式的可用键，将引发错误。

• OPTION：一个设置选项

• VALUE：该选项的值

您可以有多个 -c OPTION VALUE 部分来设置多个配置选项。

此命令返回新创建键的完整路径。使用 --dry-run 可获取此路径而不实际进行更改（也可用于验证参数）。

示例，在第一行第一列创建键，名称为 foo

$ streamdeckfs create-key ~/streamdeck-data/MYDECKSERIAL -p 20 -k 1,1 -c name foo
/home/twidi/streamdeck-data/MYDECKSERIAL/PAGE_20/KEY_ROW_1_COL_1;name=foo

或创建一个随机可用的键

$ streamdeckfs create-key ~/streamdeck-data/MYDECKSERIAL -p 20 -k '?' -c name foo
/home/twidi/streamdeck-data/MYDECKSERIAL/PAGE_20/KEY_ROW_3_COL_2;name=foo

copy-key

将在同一页或另一页上完全复制一个键（包括所有文本、图像、事件）。

streamdeckfs copy-key SERIAL_DIRECTORY -p PAGE -k KEY -tp TO_PAGE -tk ROW,COL -c OPTION1 VALUE1 -c OPTION2 VALUE2

使用以下参数：

• PAGE：要查找要复制的键的页码或名称

• KEY：要复制的键的名称，或其“位置”（例如，ROW,COL，如第一行第二个键的 1,2）

• TO_PAGE：要复制键的页码或名称（-tp 代表 --to-page）。可选：如果未指定，将使用要复制的键所在的页

• ROW,COL：新键的位置（-tk 代表 --to-key）或查找可用键的表达式。此参数为可选：如果未指定，将保持键的复制位置。可能的表达式包括

  • +：获取第一个可用的键（按行顺序）
  • ?：获取一个随机可用的键

  如果找不到匹配表达式的可用键，将引发错误。

• OPTION：要更新的一个选项

• VALUE：该选项的值

您可以有很多 -c OPTION VALUE 部分，以设置多个配置选项。如果在同一页上复制，建议设置一个与源键不同的名称。

此命令返回新创建键的完整路径。使用 --dry-run 可获取此路径而不实际进行更改（也可用于验证参数）。

示例，从页面 20 到 30 的第一行第一列创建键 foo 的副本，名称为 bar

$ streamdeckfs copy-key ~/streamdeck-data/MYDECKSERIAL -p 20 -k foo -tp 30 -tk 1,1 -c name bar
/home/twidi/streamdeck-data/MYDECKSERIAL/PAGE_30/KEY_ROW_1_COL_1;name=bar

move-key

将键移动到另一页或另一位置

streamdeckfs move-key SERIAL_DIRECTORY -p PAGE -k KEY -tp TO_PAGE -tk ROW,COL -c OPTION1 VALUE1 -c OPTION2 VALUE2

使用以下参数：

• PAGE：要查找要移动的键的页码或名称

• KEY：要移动的键的名称，或其“位置”（例如，ROW,COL，如第一行第二个键的 1,2）

• TO_PAGE：要移动键的页码或名称（-tp 代表 --to-page）。可选：如果未指定，将保持在同一页

• ROW,COL：键的新位置（-tk 代表 --to-key）或查找可用键的表达式。此参数为可选：如果未指定，将保持相同的位置。可能的表达式包括

  • +：获取第一个可用的键（按行顺序）
  • ?：获取一个随机可用的键

  如果找不到匹配表达式的可用键，将引发错误。

• OPTION：要更新的一个选项

• VALUE：该选项的值

您可以有多个 -c OPTION VALUE 部分来设置多个配置选项。

此命令返回键的新完整路径。使用 --dry-run 可获取此路径而不实际进行更改（也可用于验证参数）。

示例，将键 foo 从页面 20 到 30 的第一行第一列移动，名称为 bar

$ streamdeckfs move-key ~/streamdeck-data/MYDECKSERIAL -p 20 -k foo -tp 30 -tk 1,1 -c name bar
/home/twidi/streamdeck-data/MYDECKSERIAL/PAGE_30/KEY_ROW_1_COL_1;name=bar

delete-key

将删除所请求的键目录。

streamdeckfs delete-key SERIAL_DIRECTORY -p PAGE -k KEY

使用以下参数：

• PAGE：要查找要删除的键的页码或名称
• KEY：键的名称或其“位置”（例如 ROW,COL，例如 1,2 表示第一行的第二个键）

此命令返回被删除键目录的路径。使用 --dry-run 可获取此路径而不实际进行更改（也可用于验证参数）。

示例

$ streamdeckfs delete-key ~/streamdeck-data/MYDECKSERIAL -p spotify -k progress

list-images

将打印键的图像层。

streamdeckfs list-images SERIAL_DIRECTORY -p PAGE -k KEY DISABLED

使用以下参数：

• PAGE：要列出图像层的键的页码或名称
• KEY：要列出图像层的键的名称，或其“位置”（例如，第一行的第二个键为ROW,COL：1,2）
• DISABLED：可以是--without-disabled（默认，仅列出可渲染的图像层）或--with-disabled（列出所有图像层）

图像层按每行一个列出，每个层的结果与调用get-image-conf相同。请参阅get-image-conf以获取输出示例。

get-image-path

将打印请求图像层的完整路径。

streamdeckfs get-image-path SERIAL_DIRECTORY -p PAGE -k KEY -l LAYER

使用以下参数：

• PAGE：要查找所需图像的页面编号或名称
• KEY：要查找所需图像的键的名称，或其“位置”（例如，第一行的第二个键为ROW,COL：1,2）
• LAYER：所需层的编号或名称（如果要针对没有层的默认IMAGE...文件，可以省略整个-l LAYER部分）

示例

$ streamdeckfs get-image-path ~/streamdeck-data/MYDECKSERIAL -p spotify -k progress -l progress
/home/twidi/streamdeck-data/MYDECKSERIAL/PAGE_60;name=spotify/KEY_ROW_2_COL_4;name=progress/IMAGE;layer=0;name=progress;draw=arc;coords=0,0,100%,100%;outline=#8cc63f;width=5;angles=0,0%;angles.1=33%;opacity=50

这里可以看到angles和angles.1，因为angles.1是通过调用set-image-conf设置的

get-image-conf

将打印请求图像层的完整配置的JSON表示（包括从引用继承的选项）。

streamdeckfs get-image-conf SERIAL_DIRECTORY -p PAGE -k KEY -l LAYER

使用以下参数：

• PAGE：要查找所需图像的页面编号或名称
• KEY：要查找所需图像的键的名称，或其“位置”（例如，第一行的第二个键为ROW,COL：1,2）
• LAYER：所需层的编号或名称（如果要针对没有层的默认IMAGE...文件，可以省略整个-l LAYER部分）

示例

$ streamdeckfs get-image-conf ~/streamdeck-data/MYDECKSERIAL -p spotify -k progress -l progress
{"kind": "IMAGE", "layer": "0", "name": "progress", "draw": "arc", "coords": "0,0,100%,100%", "outline": "#8cc63f", "width": "5", "angles": "0,0%", "angles.1": "29%", "opacity": "50"}

您可以看到coords没有作为JSON数组拆分，并且angles和angles.1也没有合并。这是因为返回的配置仅基于文件名中验证过的配置选项（及其引用）。但对于边距和裁剪，您将会有具有top、left、bottom和right键的对象，但“原始”值（如字符串，如"10"或"10%"）

set-image-conf

将更新请求图像层的配置。

streamdeckfs set-image-conf SERIAL_DIRECTORY -p PAGE -k KEY -l LAYER -c OPTION1 VALUE1 -c OPTION2 VALUE2

使用以下参数：

• PAGE：要查找所需图像的页面编号或名称
• KEY：要查找所需图像的键的名称，或其“位置”（例如，第一行的第二个键为ROW,COL：1,2）
• LAYER：所需层的编号或名称（如果要针对没有层的默认IMAGE...文件，可以省略整个-l LAYER部分）
• OPTION：要更新的一个选项
• VALUE：该选项的值

你可以有多个-c OPTION VALUE部分来更新多个配置选项。要删除配置选项，将VALUE传递为一个空字符串。

此命令返回图像层的更新路径。使用--dry-run以获取此路径而不实际进行更改（也可以用于验证参数）。

例如，要更新用作圆形进度条的圆弧的结束角度

$ streamdeckfs set-image-conf ~/streamdeck-data/MYDECKSERIAL -p spotify -k progress -l progress -c angles.1 '31%'

要使进度条自动更新，您只需要在键上有一个ON_START脚本来定期获取Spotify API并使用上述命令调用您的真实收听进度。

create-image

将创建新的图像层。

streamdeckfs create-image SERIAL_DIRECTORY -p PAGE -k KEY -c OPTION1 VALUE1 -c OPTION2 VALUE2 --link LINKED_FILE

使用以下参数：

• PAGE：要创建所需图像的页面编号或名称
• KEY：要创建所需图像的键的名称，或其“位置”（例如，第一行的第二个键为ROW,COL：1,2）
• OPTION：一个设置选项
• VALUE：该选项的值
• LINKED_FILE：指向要创建符号链接的文件的可选路径。如果没有定义，将创建一个空文件。

您可以有多个 -c OPTION VALUE 部分来设置多个配置选项。

此命令返回新创建的图像层的完整路径。使用--dry-run以获取此路径而不实际进行更改（也可以用于验证参数）。

例如，要创建一个绘制红色正方形的图像层

$ streamdeckfs create-image ~/streamdeck-data/MYDECKSERIAL -p 20 -k 1,1 -c name foo -c layer 1 -c draw rectangle -c coords '20%,20%,80%,80%' -c width 0 -c fill red
/home/twidi/streamdeck-data/MYDECKSERIAL/PAGE_20/KEY_ROW_1_COL_1/IMAGE;layer=1;name=foo;draw=rectangle;coords=20%,20%,80%,80%;fill=red;width=0

或使用现有图像

$ streamdeckfs create-image ~/streamdeck-data/MYDECKSERIAL -p 20 -k 1,1 -c name foo -c layer 1 --link /path/to/my/image
/home/twidi/streamdeck-data/MYDECKSERIAL/PAGE_20/KEY_ROW_1_COL_1/IMAGE;layer=1;name=foo

copy-image

将复制图像层，在同一键或另一个键中。

streamdeckfs copy-image SERIAL_DIRECTORY -p PAGE -k KEY -l LAYER -tp TO_PAGE -tk TO_KEY -c OPTION1 VALUE1 -c OPTION2 VALUE2

使用以下参数：

• PAGE：要找到要复制的层的页面编号或名称
• KEY：要找到要复制的层的键的名称，或其“位置”（例如，第一行的第二个键为ROW,COL：1,2）
• LAYER：要复制的层的编号或名称（如果要针对没有层的默认IMAGE...文件，可以省略整个-l LAYER部分）
• TO_PAGE：要复制层的页面的编号或名称（-tp为--to-page）。可选：如果没有给出，将使用要复制的层的页面
• TO_KEY：要复制层的键名（如果是--to-key，则为-tk）。可选：如果未提供，将使用包含复制层的键位置相同的键
• OPTION：要更新的一个选项
• VALUE：该选项的值

您可以有多个-c OPTION VALUE部分来设置多个配置选项。如果复制在同一键中，建议设置一个与源层不同的层和名称。

此命令返回新创建的图像层的完整路径。使用--dry-run以获取此路径而不实际进行更改（也可以用于验证参数）。

示例，将页面20中键4,8的层foo复制到页面30中键1,1，作为第2层，名称为bar

$ streamdeckfs copy-image ~/streamdeck-data/MYDECKSERIAL -p 20 -k 4,8 -l foo -tp 30 -tk 1,1 -c layer 2 -c name bar
/home/twidi/streamdeck-data/MYDECKSERIAL/PAGE_30/KEY_ROW_1_COL_1/IMAGE;layer=2;name=bar

move-image

将图像层移动到另一个键

streamdeckfs move-image SERIAL_DIRECTORY -p PAGE -k KEY -l LAYER -tp TO_PAGE -tk TO_KEY -c OPTION1 VALUE1 -c OPTION2 VALUE2

使用以下参数：

• PAGE：要找到要移动的层的页码或名称
• KEY：要找到要移动的层的键名，或其“位置”（例如，ROW,COL，例如第一行的第二个键为1,2）
• LAYER：要移动的层的编号或名称（如果您想针对默认的IMAGE...文件，即没有层的文件，可以省略整个-l LAYER部分）
• TO_PAGE：要移动层的页码或名称（-tp是用于--to-page）。可选：如果未提供，则将保持在同一页
• TO_KEY：要移动层的键名（-tk如果用于--to-key）。可选：如果未提供，则使用包含要移动的层的键位置相同的键
• OPTION：要更新的一个选项
• VALUE：该选项的值

您可以有多个 -c OPTION VALUE 部分来设置多个配置选项。

此命令返回图像层的新的完整路径。使用--dry-run获取此路径而不实际进行更改（也可以用于验证参数）。

示例，将层foo从页面20中的键4,8移动到页面30中的键1,1，作为第2层，名称为bar

$ streamdeckfs move-image ~/streamdeck-data/MYDECKSERIAL -p 20 -k 4,8 -l foo -tp 30 -tk 1,1 -c layer 2 -c name bar
/home/twidi/streamdeck-data/MYDECKSERIAL/PAGE_30/KEY_ROW_1_COL_1/IMAGE;layer=2;name=bar

delete-image

将删除所请求的图像文件。

streamdeckfs delete-image SERIAL_DIRECTORY -p PAGE -k KEY -l LAYER

使用以下参数：

• PAGE：要找到要删除的层的页码或名称
• KEY：要找到要删除的层的键名，或其“位置”（例如，第一行的第二个键为1,2）
• LAYER：要删除的层的编号或名称（如果您想针对默认的IMAGE...文件，即没有层的文件，可以省略整个-l LAYER部分）

此命令返回已删除图像层的路径。使用--dry-run获取此路径而不实际进行更改（也可以用于验证参数）。

示例

$ streamdeckfs delete-image ~/streamdeck-data/MYDECKSERIAL -p spotify -k progress -l progress

list-images

将打印键的文本行。

streamdeckfs list-texts SERIAL_DIRECTORY -p PAGE -k KEY DISABLED

使用以下参数：

• PAGE：要找到要列出文本行的键的页码或名称
• KEY：要列出文本行的键的名称，或其“位置”（例如，第一行的第二个键为1,2）
• DISABLED：要么--without-disabled（默认值，只列出可以渲染的文本行）或--with-disabled（列出所有文本行）

文本行按每行一个列出，对于每个结果，与调用get-text-conf相同。请参阅get-text-conf以获取输出示例。

get-text-path

将打印所请求文本行的完整路径。

streamdeckfs get-text-path SERIAL_DIRECTORY -p PAGE -k KEY -l LINE

使用以下参数：

• PAGE：要找到所需文本行的页码或名称
• KEY：要找到所需文本行的键的名称，或其“位置”（例如，第一行的第二个键为1,2）
• LINE：所需文本行的编号或名称（如果您想针对默认的TEXT...文件，即没有行的文件，可以省略整个-l LINE部分）

示例

$ streamdeckfs get-text-path ~/streamdeck-data/MYDECKSERIAL -p spotify -k progress -l progress
/home/twidi/streamdeck-data/MYDECKSERIAL/PAGE_60;name=spotify/KEY_ROW_2_COL_4;name=progress/TEXT;line=1;name=progress;size=30;weight=black;color=#8cc63f;align=center;valign=middle;margin=12%,1,40%,1;text=2:23

get-text-conf

将打印所请求文本行的完整配置（包括从引用继承的选项）的JSON表示。

streamdeckfs get-text-conf SERIAL_DIRECTORY -p PAGE -k KEY -l LINE

使用以下参数：

• PAGE：要找到所需文本行的页码或名称
• KEY：要找到所需文本行的键的名称，或其“位置”（例如，第一行的第二个键为1,2）
• LINE：所需文本行的编号或名称（如果您想针对默认的TEXT...文件，即没有行的文件，可以省略整个-l LINE部分）

示例

$ streamdeckfs get-text-conf ~/streamdeck-data/MYDECKSERIAL -p spotify -k progress -l progress
{"kind": "TEXT", "line": "1", "name": "progress", "size": "30", "weight": "black", "color": "#8cc63f", "align": "center", "valign": "middle", "margin": {"top": "12%", "right": "1", "bottom": "40%", "left": "1"}}

您可以看到 margins 是一个包含 top、left、bottom 和 right 键的对象，但带有“原始”值。

set-text-conf

将更新所请求文本行的配置。

streamdeckfs set-text-conf SERIAL_DIRECTORY -p PAGE -k KEY -l LINE -c OPTION1 VALUE1 -c OPTION2 VALUE2

使用以下参数：

• PAGE：要找到所需文本行的页码或名称
• KEY：要找到所需文本行的键的名称，或其“位置”（例如，第一行的第二个键为1,2）
• LINE：所需文本行的编号或名称（如果您想针对默认的TEXT...文件，即没有行的文件，可以省略整个-l LINE部分）
• OPTION：要更新的一个选项
• VALUE：该选项的值

你可以有多个-c OPTION VALUE部分来更新多个配置选项。要删除配置选项，将VALUE传递为一个空字符串。

此命令返回文本行的更新路径。使用 --dry-run 可以获取此路径而不实际进行更改（也可以用于验证参数）。

例如，要更新显示当前曲目位置的文本

$ streamdeckfs set-text-conf ~/streamdeck-data/MYDECKSERIAL -p spotify -k progress -l progress -c text '2:36'

要使此文本自动更新，您只需要在某个按键上设置一个 ON_START 脚本，该脚本将定期获取 Spotify API 并调用上述命令以获取实际进度。或者，您可以选择避免设置 text 配置选项，并通过 get-text-path 获取路径并将文本写入文件。或者，更好（并且对您的脚本来说更快），将此 TEXT... 文件设置为一个指向包含文本的文件内的链接。 streamdeckfs 会监视符号链接指向的文件，并在文件更改时更新。因此，您可以避免调用 set-text-conf，只需更新一个最终与 streamdeckfs 无关的文件。

create-text

将创建一个新的文本行。

streamdeckfs create-text SERIAL_DIRECTORY -p PAGE -k KEY -c OPTION1 VALUE1 -c OPTION2 VALUE2 --link LINKED_FILE

使用以下参数：

• PAGE：要创建所需文本的页面编号或名称
• KEY：要创建所需文本的按键名称，或其“位置”（例如，ROW,COL，例如第一行的第二个按键为 1,2）
• OPTION：一个设置选项
• VALUE：该选项的值
• LINKED_FILE：指向要创建符号链接的文件的可选路径。如果没有定义，将创建一个空文件。

您可以有多个 -c OPTION VALUE 部分来设置多个配置选项。

此命令返回新创建的文本行的完整路径。使用 --dry-run 可以获取此路径而不实际进行更改（也可以用于验证参数）。

例如，要创建居中的文本“foo”

$ streamdeckfs create-text ~/streamdeck-data/MYDECKSERIAL -p 20 -k 1,1 -c name foo -c line 1 -c text foo -c align center -c valign middle
/home/twidi/streamdeck-data/MYDECKSERIAL/PAGE_20/KEY_ROW_1_COL_1/TEXT;line=1;name=foo;text=foo;align=center;valign=middle

或使用现有的文本文件

$ streamdeckfs create-image ~/streamdeck-data/MYDECKSERIAL -p 20 -k 1,1 -c name foo -c layer 1 --link /path/to/my/text-file
/home/twidi/streamdeck-data/MYDECKSERIAL/PAGE_20/KEY_ROW_1_COL_1/TEXT;line=1;name=foo

copy-text

将在同一按键或另一按键中复制文本行。

streamdeckfs copy-text SERIAL_DIRECTORY -p PAGE -k KEY -l LINE -tp TO_PAGE -tk TO_KEY -c OPTION1 VALUE1 -c OPTION2 VALUE2

使用以下参数：

• PAGE：要查找要复制的文本行的页面编号或名称
• KEY：要查找要复制的文本行的按键名称，或其“位置”（例如，ROW,COL，例如第一行的第二个按键为 1,2）
• LINE：要复制的文本行编号或名称（整个 -l LINE 部分可以省略，如果您想针对不带行的默认 TEXT... 文件，即不带行的文件）
• TO_PAGE：要复制文本行的页面编号或名称（-tp 是用于 --to-page 的）。可选：如果未提供，将使用要复制的文本行的页面
• TO_KEY：要复制文本行的按键名称（-tk 是用于 --to-key 的）。可选：如果未提供，将使用包含要复制的文本行的按键的同一位置的按键
• OPTION：要更新的一个选项
• VALUE：该选项的值

您可以有多个 -c OPTION VALUE 部分，以设置多个配置选项。如果复制在同一按键中，建议设置一个与源行不同的行和名称。

此命令返回新创建的文本行的完整路径。使用 --dry-run 可以获取此路径而不实际进行更改（也可以用于验证参数）。

例如，要将页面 20 中的按键 4,8 的文本行 foo 复制到页面 30 的按键 1,1，作为第 2 行，名称为 bar

$ streamdeckfs copy-text ~/streamdeck-data/MYDECKSERIAL -p 20 -k 4,8 -l foo -tp 30 -tk 1,1 -c line 2 -c name bar
/home/twidi/streamdeck-data/MYDECKSERIAL/PAGE_30/KEY_ROW_1_COL_1/TEXT;line=2;name=bar

move-text

将文本行移动到另一个按键。

streamdeckfs move-text SERIAL_DIRECTORY -p PAGE -k KEY -l LINE -tp TO_PAGE -tk TO_KEY -c OPTION1 VALUE1 -c OPTION2 VALUE2

使用以下参数：

• PAGE：要查找要移动的文本行的页面编号或名称
• KEY：要查找要移动的文本行的按键名称，或其“位置”（例如，ROW,COL，例如第一行的第二个按键为 1,2）
• LINE：要移动的文本行编号或名称（整个 -l LINE 部分可以省略，如果您想针对不带行的默认 TEXT... 文件，即不带行的文件）
• TO_PAGE：移动文本行到的页码或名称（-tp 用于 --to-page）。可选：如果没有给出，将保持在同一页
• TO_KEY：移动文本行到的键的名称（-tk 用于 --to-key）。可选：如果没有给出，将使用包含要移动文本行的键的同一位置的键
• OPTION：要更新的一个选项
• VALUE：该选项的值

您可以有多个 -c OPTION VALUE 部分来设置多个配置选项。

此命令返回键的新完整路径。使用 --dry-run 可获取此路径而不实际进行更改（也可用于验证参数）。

示例，将文本行 foo 从第 20 页的键 4,8 移动到第 30 页的键 1,1，作为第 2 行，名称为 bar

$ streamdeckfs move-text ~/streamdeck-data/MYDECKSERIAL -p 20 -k 4,8 -l foo -tp 30 -tk 1,1 -c line 2 -c name bar
/home/twidi/streamdeck-data/MYDECKSERIAL/PAGE_30/KEY_ROW_1_COL_1/TEXT;line=2;name=bar

delete-text

将删除请求的文本文件。

streamdeckfs delete-text SERIAL_DIRECTORY -p PAGE -k KEY -l LINE

使用以下参数：

• PAGE：要删除文本行的页码或名称
• KEY：要删除文本行的键的名称，或其“位置”（例如 ROW,COL，例如第一行的第二个键为 1,2）
• LINE：要删除的文本行的编号或名称（如果要针对默认的 TEXT... 文件，即没有行的文件，则可以省略整个 -l LINE 部分）

此命令返回删除的文本行文件的路径。使用 --dry-run 获取此路径而无需实际进行更改（也可以用于验证参数）。

示例

$ streamdeckfs delete-text ~/streamdeck-data/MYDECKSERIAL -p spotify -k progress -l progress

list-events

将打印牌组、页面或键的事件。

streamdeckfs list-events SERIAL_DIRECTORY -p PAGE -k KEY DISABLED

使用以下参数：

• PAGE：要列出事件的页码或名称，或者如果传递了 -k，则查找要列出事件的键的位置。不要传递此参数以列出牌组的事件
• KEY：要列出事件的键的名称，或其“位置”（例如第一行的第二个键为 1,2）。不要传递此参数以列出页面或牌组的事件
• DISABLED：要么 --without-disabled（默认值，仅列出可以渲染的事件）要么 --with-disabled（列出所有事件）

事件按输出行逐个列出，每个事件的结果与调用 get-event-conf 的结果相同。有关输出示例，请参阅 get-event-conf。

get-event-path

将打印请求事件的完整路径。

streamdeckfs get-event-path SERIAL_DIRECTORY -p PAGE -k KEY -e EVENT

使用以下参数：

• PAGE：要查找请求事件的页码或名称。不要传递此参数以查找牌组事件
• KEY：要查找请求事件的键的名称，或其“位置”（例如第一行的第二个键为 1,2）。不要传递此参数以查找页面或牌组事件
• EVENT：事件的类型（对于键事件，为 start、end、press、longpress 或 release，对于页面或牌组事件，为 start 或 end）或请求事件的名称

示例

$ streamdeckfs get-event-path ~/streamdeck-data/MYDECKSERIAL -p spotify -k seek-backward -e press
/home/twidi/streamdeck-data/MYDECKSERIAL/PAGE_60;name=spotify/KEY_ROW_2_COL_2;name=seek-backward/ON_PRESS;every=1000;unique

get-event-conf

将打印请求事件的完整配置（包括从引用继承的选项）的 JSON 表示形式。

streamdeckfs get-event-conf SERIAL_DIRECTORY -p PAGE -k KEY -e EVENT

使用以下参数：

• PAGE：要查找请求事件的页码或名称。不要传递此参数以查找牌组事件
• KEY：要查找请求事件的键的名称，或其“位置”（例如第一行的第二个键为 1,2）。不要传递此参数以查找页面或牌组事件
• EVENT：事件的类型（对于键事件，为 start、end、press、longpress 或 release，对于页面或牌组事件，为 start 或 end）或请求事件的名称

示例

$ streamdeckfs get-event-conf ~/streamdeck-data/MYDECKSERIAL -p spotify -k seek-backward -e press
{"kind": "PRESS", "every": "1000", "unique": true}

set-event-conf

将更新请求事件的配置。

streamdeckfs set-event-conf SERIAL_DIRECTORY -p PAGE -k KEY -e EVENT -c OPTION1 VALUE1 -c OPTION2 VALUE2

使用以下参数：

• PAGE：要查找请求事件的页码或名称。不要传递此参数以查找牌组事件
• KEY：要查找请求事件的键的名称，或其“位置”（例如第一行的第二个键为 1,2）。不要传递此参数以查找页面或牌组事件
• EVENT：事件的类型（对于键事件，为 start、end、press、longpress 或 release，对于页面或牌组事件，为 start 或 end）或请求事件的名称
• OPTION：要更新的一个选项
• VALUE：该选项的值

你可以有多个-c OPTION VALUE部分来更新多个配置选项。要删除配置选项，将VALUE传递为一个空字符串。

此命令返回事件的更新路径。使用 --dry-run 获取此路径而无需实际进行更改（也可以用于验证参数）。

示例，停止允许重复

$ streamdeckfs set-event-conf ~/streamdeck-data/MYDECKSERIAL -p spotify -k seek-backward -e press -c every ''

为 every 配置选项传递空字符串将移除它从文件名中，正如我们通过调用 get-event-path 和 get-event-conf 看到的

$ streamdeckfs get-event-path ~/streamdeck-data/MYDECKSERIAL -p spotify -k seek-backward -e press
/home/twidi/streamdeck-data/MYDECKSERIAL/PAGE_60;name=spotify/KEY_ROW_2_COL_2;name=seek-backward/ON_PRESS;every=1000;unique

$ streamdeckfs get-event-conf ~/streamdeck-data/MYDECKSERIAL -p spotify -k seek-backward -e press
{"kind": "PRESS", "unique": true}

如果事件上的操作是设置变量内容（ON_PRESS;VAR_NAME<=VALUE），请注意键/值分隔符是 =，因此 < 在 -c 参数的第一部分

$ streamdeckfs set-event-conf ~/streamdeck-data/MYDECKSERIAL -p page -k key -e press -c 'VAR_NAME<' VALUE

create-event

将创建新事件。

streamdeckfs create-event SERIAL_DIRECTORY -p PAGE -k KEY -e EVENT -c OPTION1 VALUE1 -c OPTION2 VALUE2 --link LINKED_FILE

使用以下参数：

• 页面：要创建事件的目标页面的编号或名称。对于牌组事件，不要传递此参数。
• 键：要创建事件的目标键的名称，或其“位置”（例如 ROW,COL，例如第一行第二个键为 1,2）。对于页面或牌组事件，不要传递此参数。
• 事件：要创建的事件的类型（对于键事件，为 start、end、press、longpress 或 release，对于页面或牌组事件，为 start 或 end）。
• OPTION：一个设置选项
• VALUE：该选项的值
• LINKED_FILE：指向要创建符号链接的文件的可选路径。如果没有定义，将创建一个空文件。

您可以有多个 -c OPTION VALUE 部分来设置多个配置选项。

此命令返回新创建事件的完整路径。使用 --dry-run 获取此路径而不实际进行更改（也可以用于验证参数）。

例如，当按键时创建一个启动 gnome-calculator 的事件。

$ streamdeckfs create-event ~/streamdeck-data/MYDECKSERIAL -p 20 -k 1,1 --link "$(which gnome-calculator)"
/home/twidi/streamdeck-data/MYDECKSERIAL/PAGE_20/KEY_ROW_1_COL_1/ON_PRESS

copy-event

将复制一个事件，对于键事件，在相同键或另一键，对于页面事件，在相同页面或另一页面。

streamdeckfs copy-event SERIAL_DIRECTORY -p PAGE -k KEY -e EVENT -tp TO_PAGE -tk TO_KEY -te TO_EVENT -c OPTION1 VALUE1 -c OPTION2 VALUE2

使用以下参数：

• 页面：要查找要复制的事件的页面的编号或名称。对于牌组事件，不要传递此参数。
• 键：要查找要复制的事件的键的名称，或其“位置”（例如 ROW,COL，例如第一行第二个键为 1,2）。对于页面或牌组事件，不要传递此参数。
• 事件：要复制的事件的类型（对于键事件，为 start、end、press、longpress 或 release，对于页面或牌组事件，为 start 或 end）或名称。
• TO_PAGE：要复制事件的页面的编号或名称（-tp 为 --to-page）。可选：如果没有给出，将使用要复制的事件所在的页面。对于牌组事件，不要传递此参数。
• TO_KEY：要复制事件的键的名称（-tk 为 --to-key）。可选：如果没有给出，将使用包含要复制的事件的键在同一位置的键。对于页面或牌组事件，不要传递此参数。
• TO_EVENT：新事件的新类型（对于键事件，为 start、end、press、longpress 或 release，对于页面或牌组事件，为 start 或 end）。可选：如果没有给出，将使用与要复制的事件相同的类型。
• OPTION：要更新的一个选项
• VALUE：该选项的值

您可以有多个 -c OPTION VALUE 部分，以设置多个配置选项。如果复制在同一页面/键中，建议设置与源事件不同的类型和名称。

此命令返回新创建事件的完整路径。使用 --dry-run 获取此路径而不实际进行更改（也可以用于验证参数）。

例如，从页面 20 的键 4,8 的 ON_PRESS 事件创建一个副本到页面 30 的键 1,1。

$ streamdeckfs copy-event ~/streamdeck-data/MYDECKSERIAL -p 20 -k 4,8 -e press -tp 30 -tk 1,1
/home/twidi/streamdeck-data/MYDECKSERIAL/PAGE_30/KEY_ROW_1_COL_1/ON_PRESS

move-event

将事件移动到另一个键（对于键事件），或将事件移动到另一个页面（对于页面事件）。

streamdeckfs move-event SERIAL_DIRECTORY -p PAGE -k KEY -e EVENT -tp TO_PAGE -tk TO_KEY -te TO_EVENT -c OPTION1 VALUE1 -c OPTION2 VALUE2

使用以下参数：

• 页面：要查找要移动的事件的页面的编号或名称。对于牌组事件，不要传递此参数。
• 键：要查找要移动的事件的键的名称，或其“位置”（例如 ROW,COL，例如第一行第二个键为 1,2）。对于页面或牌组事件，不要传递此参数。
• 事件：要移动的事件的类型（对于键事件，为 start、end、press、longpress 或 release，对于页面或牌组事件，为 start 或 end）或名称。
• TO_PAGE：要移动事件的页面的编号或名称（-tp 为 --to-page）。可选：如果没有给出，将保持在同一页面。对于牌组事件，不要传递此参数。
• TO_KEY：要移动事件的键的名称（-tk 为 --to-key）。可选：如果没有给出，将使用包含要移动的事件的键在同一位置的键。对于页面或牌组事件，不要传递此参数。
• TO_EVENT：移动事件的类型（对于按键事件，可以是start、end、press、longpress或release；对于页面或牌组事件，可以是start或end）。可选：如果未提供，将使用与移动事件相同的类型。
• OPTION：要更新的一个选项
• VALUE：该选项的值

您可以有多个 -c OPTION VALUE 部分来设置多个配置选项。

此命令返回事件的新的完整路径。使用--dry-run获取此路径而不实际执行更改（也可以用于验证参数）。

例如，要将页面20中按键4,8的ON_PRESS事件移动到页面30中按键1,1，

$ streamdeckfs move-event ~/streamdeck-data/MYDECKSERIAL -p 20 -k 4,8 -e press -tp 30 -tk 1,1
/home/twidi/streamdeck-data/MYDECKSERIAL/PAGE_30/KEY_ROW_1_COL_1/ON_PRESS

delete-event

将删除请求的事件文件。

streamdeckfs delete-event SERIAL_DIRECTORY -p PAGE -k KEY -e EVENT

使用以下参数：

• PAGE：要查找要删除的事件的页面编号或名称。对于牌组事件，不要传递此参数
• KEY：要查找要删除的事件的按键名称，或其“位置”（例如，ROW,COL，例如第一行的第二个按键的1,2）。对于页面或牌组事件，不要传递此参数
• EVENT：要删除的事件的类型（对于按键事件，可以是start、end、press、longpress或release；对于页面或牌组事件，可以是start或end）或名称

此命令返回已删除事件的路径。使用--dry-run获取此路径而不实际执行更改（也可以用于验证参数）。

示例

$ streamdeckfs delete-event ~/streamdeck-data/MYDECKSERIAL -p spotify -k progress -e press

list-vars

将打印牌组、页面或按键的变量。

streamdeckfs list-vars SERIAL_DIRECTORY -p PAGE -k KEY DISABLED

使用以下参数：

• PAGE：要列出变量的页面编号或名称，或如果传递了-k，则找到要列出变量的按键位置。列出牌组的变量时，不要传递此参数
• KEY：要列出变量的按键名称，或其“位置”（例如，第一行的第二个按键的1,2）。列出页面或牌组的变量时，不要传递此参数
• DISABLED：可以是--without-disabled（默认，仅列出可渲染的变量）或--with-disabled（列出所有变量）

变量按每行一个列出，每行的结果与调用get-var-conf相同。有关输出示例，请参阅get-var-conf。

get-var-path

将打印请求变量的完整路径。

streamdeckfs get-var-path SERIAL_DIRECTORY -p PAGE -k KEY -v VAR

使用以下参数：

• PAGE：要查找所需变量的页面编号或名称。请求牌组变量时，不要传递此参数
• KEY：要查找所需变量的按键名称，或其“位置”（例如，第一行的第二个按键的1,2）。请求页面或牌组变量时，不要传递此参数
• VAR：变量的名称（只能包含从A到Z的大写字母、从0到9的数字以及字符_，不能以数字或_开头，也不能以_结尾）。可能以VAR_开头。

示例

$ streamdeckfs get-var-path ~/streamdeck-data/MYDECKSERIAL -p spotify -v ALBUM
/home/twidi/streamdeck-data/MYDECKSERIAL/PAGE_60;name=spotify/VAR_ALBUM

get-var-conf

将打印请求变量的完整配置（包括从引用继承的选项）的JSON表示形式。

streamdeckfs get-var-conf SERIAL_DIRECTORY -p PAGE -k KEY -v VAR

使用以下参数：

• PAGE：要查找所需变量的页面编号或名称。请求牌组变量时，不要传递此参数
• KEY：要查找所需变量的按键名称，或其“位置”（例如，第一行的第二个按键的1,2）。请求页面或牌组变量时，不要传递此参数
• VAR：变量的名称（只能包含从A到Z的大写字母、从0到9的数字以及字符_，不能以数字或_开头，也不能以_结尾）。可能以VAR_开头。

示例

$ streamdeckfs get-var-conf ~/streamdeck-data/MYDECKSERIAL -p spotify -v ALBUM
{"kind": "VAR", "name": "ALBUM"}

get-var-value

将打印请求变量的值。

streamdeckfs get-var-value SERIAL_DIRECTORY -p PAGE -k KEY -v VAR

使用以下参数：

• PAGE：要查找所需变量的页面编号或名称。请求牌组变量时，不要传递此参数
• KEY：要查找所需变量的按键名称，或其“位置”（例如，第一行的第二个按键的1,2）。请求页面或牌组变量时，不要传递此参数
• VAR：变量的名称（只能包含从A到Z的大写字母、从0到9的数字以及字符_，不能以数字或_开头，也不能以_结尾）。可能以VAR_开头。

变量不需要在请求的按键或页面中，只要它在其中一个父级（当请求按键变量时为页面或牌组，当请求页面变量时为牌组）中即可。

如果变量存在但没有值（没有内容，没有value配置选项或没有链接的文件），则不会打印任何内容（但不会引发错误）。

示例

$ streamdeckfs get-var-value ~/streamdeck-data/MYDECKSERIAL -p spotify -v ALBUM
Discovery

set-var-conf

将更新请求变量的配置。

streamdeckfs set-var-conf SERIAL_DIRECTORY -p PAGE -k KEY -v VAR -c OPTION1 VALUE1 -c OPTION2 VALUE2

使用以下参数：

• PAGE：要查找所需变量的页面编号或名称。请求牌组变量时，不要传递此参数
• KEY：要查找所需变量的按键名称，或其“位置”（例如，第一行的第二个按键的1,2）。请求页面或牌组变量时，不要传递此参数
• VAR：变量的名称（只能包含从A到Z的大写字母、从0到9的数字以及字符_，不能以数字或_开头，也不能以_结尾）。可能以VAR_开头。
• OPTION：要更新的一个选项
• VALUE：该选项的值

你可以有多个-c OPTION VALUE部分来更新多个配置选项。要删除配置选项，将VALUE传递为一个空字符串。

此命令返回变量的更新路径。使用--dry-run获取此路径而不实际执行更改（也可以用于验证参数）。

例如，要设置变量的值

$ streamdeckfs set-var-conf ~/streamdeck-data/MYDECKSERIAL -p spotify -v ALBUM -c value Discovery
/home/twidi/streamdeck-data/MYDECKSERIAL/PAGE_60;name=spotify/VAR_ALBUM;value=Discovery

创建变量

将创建一个新变量。

streamdeckfs create-var SERIAL_DIRECTORY -p PAGE -k KEY -v VAR -c OPTION1 VALUE1 -c OPTION2 VALUE2 --link LINKED_FILE

使用以下参数：

• PAGE：要创建所需变量的页面编号或名称。对于牌组变量，不要传递此参数。
• KEY：要创建所需变量的键的名称，或其“位置”（例如，ROW,COL，例如第一行的第二个键的1,2）。对于页面或牌组变量，不要传递此参数。
• VAR：要创建的变量名称（只能包含从 A 到 Z 的字母，从 0 到 9 的数字，以及字符 _，不能以数字或 _ 开头，也不能以 _ 结尾）。可能以 VAR_ 前缀。
• OPTION：一个设置选项
• VALUE：该选项的值
• LINKED_FILE：指向要创建符号链接的文件的可选路径。如果没有定义，将创建一个空文件。

您可以有多个 -c OPTION VALUE 部分来设置多个配置选项。

此命令返回新创建变量的完整路径。使用 --dry-run 获取此路径而不实际进行更改（也可以用于验证参数）。

示例

$ streamdeckfs create-var ~/streamdeck-data/MYDECKSERIAL -p spotify -v ALBUM -c value Homework
/home/twidi/streamdeck-data/MYDECKSERIAL/PAGE_60;name=spotify/VAR_ALBUM;value=Homework

复制变量

将复制一个变量，在同一个键或另一个键变量中，或在同一页面或另一个页面变量中

streamdeckfs copy-var SERIAL_DIRECTORY -p PAGE -k KEY -v VAR -tp TO_PAGE -tk TO_KEY -tv TO_VAR -c OPTION1 VALUE1 -c OPTION2 VALUE2

使用以下参数：

• PAGE：要查找要复制的变量的页面编号或名称。对于牌组变量，不要传递此参数。
• KEY：要查找要复制的变量的键的名称，或其“位置”（例如，ROW,COL，例如第一行的第二个键的1,2）。对于页面或牌组变量，不要传递此参数。
• VAR：要复制的变量名称（只能包含从 A 到 Z 的字母，从 0 到 9 的数字，以及字符 _，不能以数字或 _ 开头，也不能以 _ 结尾）。可能以 VAR_ 前缀。
• TO_PAGE：要复制变量的页面编号或名称（-tp 是 --to-page 的缩写）。可选：如果未提供，将使用变量要复制的页面。对于牌组变量，不要传递此参数。
• TO_KEY：要复制变量的键的名称（-tk 是 --to-key 的缩写）。可选：如果未提供，将使用包含要复制的变量的相同位置的键。对于页面或牌组变量，不要传递此参数。
• TO_VAR：新变量的名称（只能包含从 A 到 Z 的字母，从 0 到 9 的数字，以及字符 _，不能以数字或 _ 开头，也不能以 _ 结尾）。可选：如果未提供，将使用与要复制的变量相同的名称。可能以 VAR_ 前缀。
• OPTION：要更新的一个选项
• VALUE：该选项的值

您可以使用多个 -c OPTION VALUE 部分来设置多个配置选项。如果复制在同一页面/键中，建议设置一个与源变量不同的名称。

此命令返回新创建变量的完整路径。使用 --dry-run 获取此路径而不实际进行更改（也可以用于验证参数）。

示例

$ streamdeckfs copy-var ~/streamdeck-data/MYDECKSERIAL -p spotify -v ALBUM -tv ARTIST -c value 'Daft Punk'
/home/twidi/streamdeck-data/MYDECKSERIAL/PAGE_60;name=spotify/VAR_ARTIST;value=Daft Punk

移动变量

将变量移动到另一个键（对于键变量）或另一个页面（对于页面变量）

streamdeckfs move-var SERIAL_DIRECTORY -p PAGE -k KEY -v VAR -tp TO_PAGE -tk TO_KEY -tv TO_VAR -c OPTION1 VALUE1 -c OPTION2 VALUE2

使用以下参数：

• PAGE：要查找要移动的变量的页面编号或名称。对于牌组变量，不要传递此参数。
• KEY：要查找要移动的变量的键的名称，或其“位置”（例如，ROW,COL，例如第一行的第二个键的1,2）。对于页面或牌组变量，不要传递此参数。
• VAR：要移动的变量名称（只能包含从 A 到 Z 的字母，从 0 到 9 的数字，以及字符 _，不能以数字或 _ 开头，也不能以 _ 结尾）。可能以 VAR_ 前缀。
• TO_PAGE：要移动变量的页面编号或名称（-tp 是 --to-page 的缩写）。可选：如果未提供，将保持在同一页面。对于牌组变量，不要传递此参数。
• TO_KEY：要移动变量的键的名称（-tk 是 --to-key 的缩写）。可选：如果未提供，将使用包含要移动的变量的相同位置的键。对于页面或牌组变量，不要传递此参数。
• TO_VAR：被移动变量的名称（只能包含大写字母 A 到 Z，数字 0 到 9，以及字符 _，不能以数字或 _ 开头，也不能以 _ 结尾）。可选：如果没有给出，将使用移动变量的相同名称。可以由 VAR_ 前缀。
• OPTION：要更新的一个选项
• VALUE：该选项的值

您可以有多个 -c OPTION VALUE 部分来设置多个配置选项。

此命令返回变量的新完整路径。使用 --dry-run 获取此路径而不进行实际更改（也可以用于验证参数）。

示例

$ streamdeckfs move-var ~/streamdeck-data/MYDECKSERIAL -p spotify -v ALBUM -tv ARTIST -c value 'Daft Punk'
/home/twidi/streamdeck-data/MYDECKSERIAL/PAGE_60;name=spotify/VAR_ARTIST;value=Daft Punk

delete-var

将删除请求的变量文件。

streamdeckfs delete-var SERIAL_DIRECTORY -p PAGE -k KEY -v VAR

使用以下参数：

• PAGE：要找到要删除变量的页面编号或名称。对于牌变量，不要传递此参数。
• KEY：要找到要删除变量的键的名称，或其“位置”（例如 ROW,COL，例如第一行的第二个键为 1,2）。对于页面或牌变量，不要传递此参数。
• VAR：要删除的变量名称（只能包含大写字母 A 到 Z，数字 0 到 9，以及字符 _，不能以数字或 _ 开头，也不能以 _ 结尾）。可以由 VAR_ 前缀。

此命令返回已删除变量文件的路径。使用 --dry-run 获取此路径而不进行实际更改（也可以用于验证参数）。

示例

$ streamdeckfs delete-var ~/streamdeck-data/MYDECKSERIAL -p spotify -v ALBUM

示例配置

您可以在 示例目录 中找到示例配置，该目录位于 Git 仓库。

Web 渲染器

默认情况下，在执行 run 命令时，牌组也可以通过 http://0.0.0.0:1910 地址在网页浏览器中访问，无需密码。

配置

您可以通过传递 --no-web 选项来禁用 Web 服务器。

但如果没有，有一些选项可以更改 Web 服务器的行为

• --web：允许使用与默认地址或端口不同的地址或端口 http://0.0.0.0:1910。您可以传递

  • 端口号，例如 --web 8080 将使用地址 http://0.0.0.0:8080。
  • IP 地址 + 端口号，例如 --web 127.0.0.1:8080
  • 完全限定域名 + 端口号，例如 --web mycomputer.local:8080

• --web-password：这是一个标志，将在提示时请求密码，该密码将需要访问浏览器中的牌组

• --ssl-cert：SSL 证书文件的路径以激活 https

• --ssl-key：用于生成证书的 SSL 私钥文件的路径

要生成本地自签名证书，可以使用以下命令

 openssl req -new -newkey rsa:4096 -days 3650 -nodes -x509 -subj "/C=<Country Code>/ST=<State>/L=<City>/O=<Organization>/CN=<Common Name>" -keyout certificate.key -out certificate.crt

不要忘记用 < 和 >（包括 < 和 >）之间的值替换（包括 < 和 >）

用法

当访问地址时（显示在 run 命令输出的开头），将显示所有 StreamDecks 的列表。单击其中一个将转到牌组页面。

当牌组上的键被更新时，网页上的键也会进行视觉更新。通过按下键周围的白色边框可以查看来自牌组的按下/释放事件。

当然，您可以在网页浏览器中单击/轻触一个键来模拟在牌组上的单击。要模拟在牌组上的长按，只需将单击/轻触保持一段时间即可。

如果需要密码，您将被重定向到输入密码的页面，然后如果一切正常，您将被重定向回所需的页面。

在浏览器中正确处理未连接的牌组，因此可以在不影响网页使用的情况下插拔牌组。

要显示全屏牌组，请双击“空”区域（即，不在键上）。

虚拟牌组（即“网页牌组”）

您可以在没有实际 Stream Decks 的情况下使用 streamdeckfs！或者创建虚拟的牌组，以补充您已经拥有的牌组。我们称这些虚拟牌组为“网页牌组”。

要创建“网页牌组”，请使用命令 create-web-deck

streamdeckfs create-web-deck BASE_DIRECTORY -s SERIAL -r NB_ROWS -c NB_COLS

使用以下参数：

• DIRECTORY：创建网页牌组的配置目录所在的目录
• SERIAL：新网页牌组的序列号。它是一个由12个字符组成的字符串（只能包含从A到Z的大写字母和从0到9的数字），以W开头（真实Stream Deck的序列号格式相同，除了第一个字母取决于型号）
• NB_ROWS：网页牌组的行数。从1到8
• NB_COLS：网页牌组的列数。从1到12

要更改已创建的网页牌组的行数或列数，请使用新值重复命令，其余的配置（页面、按键...）将保持不变。

创建网页牌组后，您可以像这样使用make-dirs命令

streamdeckfs make-dirs SERIAL BASE_DIRECTORY --pages PAGES