| WPCTL(1) | WirePlumber | WPCTL(1) |
نام (NAME)
wpctl - رابط خط فرمانی کنترل WirePlumber
خلاصه دستور (SYNOPSIS)
wpctl [COMMAND] [COMMAND_OPTIONS]
توضیحات (DESCRIPTION)
wpctl یک ابزار کنترلی خط فرمانی برای WirePlumber، مدیر نشست PipeWire است. این ابزار رابطی را برای بررسی، کنترل و پیکربندی دستگاه‌های صوتی و تصویری، گره‌ها (nodes) و ویژگی‌های آن‌ها در سرور رسانه PipeWire فراهم می‌کند.
WirePlumber وظیفهٔ مدیریت مسیریابی صدا و تصویر، پیکربندی دستگاه‌ها و سیاست‌های نشست را بر عهده دارد. wpctl به کاربران اجازه می‌دهد با این مؤلفه‌ها تعامل داشته باشند، بلندی صدا را تغییر دهند، دستگاه‌های پیش‌فرض را تعیین کنند، ویژگی‌های اشیاء را بررسی نمایند و تنظیمات را تغییر دهند.
دستورات (COMMANDS)
status
wpctl status [-k|--nick] [-n|--name]
وضعیت فعلی اشیاء را در PipeWire، از جمله دستگاه‌ها، سینک‌ها (sinks)، منابع (sources)، فیلترها و جریان‌ها (streams) نمایش می‌دهد. همچنین یک نمای سلسله‌مراتبی از سامانهٔ صوتی/تصویری ارائه می‌دهد.
- گزینه‌ها:
- -k, --nick
- نمایش نام مستعار (nickname) دستگاه و گره به جای توضیحات
- -n, --name
- نمایش نام دستگاه و گره به جای توضیحات
list
wpctl list [audio|video] [devices|sinks|sources]
فهرستی ماشین‌خوان از اشیاء PipeWire را نمایش می‌دهد که می‌توان آن را به صورت اختیاری بر اساس نوع رسانه و نوع شیء فیلتر کرد. هر خط از خروجی شامل فیلدهای جداشده با تب است: شناسه شیء (ID)، نام، نوع رسانه/نوع شیء، و در صورتی که گره پیش‌فرض فعلی باشد، یک علامت *.
- آرگومان‌ها:
- audio|video (اختیاری)
- فیلتر کردن بر اساس نوع رسانه
- devices|sinks|sources (اختیاری)
- فیلتر کردن بر اساس نوع شیء (ابتدا نیازمند تعیین نوع رسانه است)
wpctl get-volume ID
اطلاعات بلندی صدای گره مشخص‌شده، شامل سطح کنونی بلندی صدا و وضعیت بی‌صدا بودن (mute) را نمایش می‌دهد.
- آرگومان‌ها:
- ID
- شناسه گره (Node ID) یا شناسه ویژه (بخش «شناسه‌های ویژه» (SPECIAL IDENTIFIERS) را ببینید)
inspect
wpctl inspect ID [-r|--referenced] [-a|--associated]
اطلاعات تفصیلی درباره شیء مشخص‌شده، از جمله تمامی ویژگی‌ها و فراداده‌ها را نمایش می‌دهد.
- آرگومان‌ها:
- ID
- شناسه شیء یا شناسه ویژه
- گزینه‌ها:
- -r, --referenced
- نمایش اشیایی که در ویژگی‌ها به آن‌ها ارجاع داده شده است
- -a, --associated
- نمایش اشیاء مرتبط
set-default
wpctl set-default ID
گره دستگاه مشخص‌شده را به عنوان مقصد پیش‌فرض از نوع خود (ضبط یا بازپخش) برای جریان‌های جدیدی که به اتصال خودکار نیاز دارند، تنظیم می‌کند.
این انتخاب پس از راه‌اندازی‌های مجدد، در فایل وضعیت default-nodes <#state-locations> به خاطر سپرده می‌شود و نسبت به انتخاب خودکار و مبتنی بر اولویتی که در غیر این صورت WirePlumber انجام می‌داد، ارجحیت دارد. برای لغو آن از clear-default استفاده کنید.
- آرگومان‌ها:
- ID
- شناسه گره sink یا source
set-volume
wpctl set-volume ID VOL[%][-|+] [-p|--pid] [-l LIMIT|--limit LIMIT]
بلندی صدای گره مشخص‌شده را تنظیم می‌کند.
- آرگومان‌ها:
- ID
- شناسه گره، شناسه ویژه، یا PID (همراه با --pid)
- VOL[%][-|+]
- مشخصه بلندی صدا:
- VOL - تنظیم بلندی صدا روی یک مقدار مشخص (1.0 = 100%)
- VOL% - تنظیم بلندی صدا بر حسب درصد (50% = 0.5)
- VOL+ - افزایش بلندی صدا به مقدار مشخص
- VOL- - کاهش بلندی صدا به مقدار مشخص
- VOL%+ - افزایش بلندی صدا بر حسب درصد
- VOL%- - کاهش بلندی صدا بر حسب درصد
- گزینه‌ها:
- -p, --pid
- در نظر گرفتن ID به عنوان شناسه فرایند (PID) و اعمال تغییرات روی تمام گره‌های مرتبط با آن
- -l LIMIT, --limit LIMIT
- محدود کردن بلندی نهایی صدا به مقداری کمتر از این مقدار (عدد ممیز شناور، 1.0 = 100%)
- مثال‌ها:
- تنظیم
بلندی صدا
روی 50%: wpctl set-volume @DEFAULT_SINK@ 0.5
افزایش بلندی صدا به اندازه 10%: wpctl set-volume 42 10%+
تنظیم بلندی صدا برای تمام گره‌های PID 1234: wpctl set-volume --pid 1234 0.8
wpctl set-mute ID 1|0|toggle [-p|--pid]
وضعیت بی‌صدا بودن گره مشخص‌شده را تغییر می‌دهد.
set-profile
wpctl set-profile ID INDEX
پروفایل دستگاه مشخص‌شده را روی نمایهٔ داده‌شده تنظیم می‌کند.
set-route
wpctl set-route ID INDEX
مسیر (route) دستگاه مشخص‌شده را روی نمایهٔ داده‌شده تنظیم می‌کند.
clear-default
wpctl clear-default [ID]
گره پیش‌فرض پیکربندی‌شده را پاک می‌کند. اگر هیچ شناسه‌ای مشخص نشود، تمام گره‌های پیش‌فرض را پاک می‌کند.
این کار انتخاب‌های فعلی و تمام انتخاب‌های قبلی set-default از آن نوع را فراموش می‌کند تا WirePlumber به انتخاب خودکار گره پیش‌فرض بر اساس ویژگی priority.session هر گره بازگردد. این دستور زمانی لازم است که اولویت پیکربندی‌شده بی‌اثر به نظر می‌رسد، چرا که انتخاب‌های ذخیره‌شده بر هر اولویتی ارجحیت دارند. انتخاب‌های ذخیره‌شده در بخش "Default Configured Devices" از خروجی status فهرست شده‌اند.
- آرگومان‌ها:
- ID (اختیاری)
- شناسهٔ تنظیمات برای پاک‌سازی (0-2 برای Audio/Sink، Audio/Source، Video/Source). در صورت حذف، تمام پیش‌فرض‌ها را پاک می‌کند.
wpctl settings [KEY] [VAL] [-d|--delete] [-s|--save] [-r|--reset]
تنظیمات WirePlumber را نمایش می‌دهد، تغییر می‌دهد، یا حذف می‌کند.
- آرگومان‌ها:
- KEY (اختیاری)
- نام کلید تنظیمات
- VAL (اختیاری)
- مقدار تنظیمات (در قالب JSON)
- گزینه‌ها:
- -d, --delete
- حذف مقدار ذخیره‌شدهٔ تنظیمات (مشخص نکردن KEY به معنی حذف همه است)
- -s, --save
- ذخیرهٔ مقدار تنظیمات (مشخص نکردن KEY به معنی ذخیرهٔ همه، و مشخص نکردن VAL به معنی ذخیرهٔ مقدار فعلی است)
- -r, --reset
- بازنشانی تنظیمات به مقدار پیش‌فرض آن
- رفتار:
- بدون آرگومان: نمایش تمام تنظیمات
- فقط KEY: نمایش مقدار تنظیمات مشخص‌شده
- هم KEY و هم VAL: تعیین مقدار تنظیمات مشخص‌شده
set-log-level
wpctl set-log-level [ID] LEVEL
سطح لاگ (گزارش‌گیری) یک کلاینت را تنظیم می‌کند.
- آرگومان‌ها:
- ID (اختیاری)
- شناسهٔ کلاینت. در صورت عدم ذکر، روی WirePlumber اعمال می‌شود. برای سرور PipeWire از 0 استفاده کنید.
- LEVEL
- سطح لاگ (مانند 0، 1، 2، 3، 4، 5، E، W، N، I، D، T). برای لغو تنظیم سطح لاگ از - استفاده کنید.
reset
wpctl reset [-c|--wireplumber-config] [-p|--pipewire-config] [-a|--all] [-n|--no-restart] [-d|--dry-run] [-y|--yes]
با حذف فایل‌های وضعیت و پیکربندی، WirePlumber (و در صورت تمایل PipeWire) را به مقادیر پیش‌فرض بازنشانی می‌کند. به‌طور پیش‌فرض، تنها دایرکتوری وضعیت WirePlumber (~/.local/state/wireplumber) حذف می‌شود. WirePlumber به‌طور خودکار پیش از حذف متوقف شده و پس از آن مجدداً راه‌اندازی می‌شود، مگر اینکه --no-restart داده شده باشد. قبل از حذف هر فایلی یک اعلان تأیید نمایش داده می‌شود، مگر اینکه گزینهٔ --yes داده شده باشد.
این دستور نیازی به نشست فعال PipeWire ندارد.
- گزینه‌ها:
- -c, --wireplumber-config
- فایل‌های پیکربندی کاربر WirePlumber (~/.config/wireplumber) را نیز حذف می‌کند
- -p, --pipewire-config
- فایل‌های پیکربندی کاربر PipeWire (~/.config/pipewire) را نیز حذف کرده و سرویس PipeWire را مجدداً راه‌اندازی می‌کند
- -a, --all
- تمام فایل‌های وضعیت و پیکربندی را حذف می‌کند (معادل ترکیب -c و -p)
- -n, --no-restart
- پس از حذف فایل‌ها، سرویس‌ها را متوقف یا راه‌اندازی مجدد نمی‌کند
- -d, --dry-run
- بدون حذف واقعی چیزی یا راه‌اندازی مجدد سرویس‌ها، نشان می‌دهد چه فایل‌هایی حذف خواهند شد
- -y, --yes
- بدون درخواست تأیید، عملیات را ادامه می‌دهد
دستور wpctl به جای شناسه‌های عددی، این شناسه‌های ویژه را برای مقادیر پیش‌فرض پرکاربرد می‌پذیرد:
- @DEFAULT_SINK@، @DEFAULT_AUDIO_SINK@
- سینک صوتی پیش‌فرض فعلی (دستگاه پخش)
- @DEFAULT_SOURCE@، @DEFAULT_AUDIO_SOURCE@
- منبع صوتی پیش‌فرض فعلی (دستگاه ضبط)
- @DEFAULT_VIDEO_SOURCE@
- منبع ویدیویی پیش‌فرض فعلی (دوربین)
این شناسه‌ها در زمان اجرا به شناسه‌های گره مربوطه تبدیل می‌شوند.
وضعیت خروج (EXIT STATUS)
wpctl کدهای خروج زیر را بازمی‌گرداند:
- 0
- موفقیت
- 1
- خطای عمومی (مانند آرگومان‌های نامعتبر، خطای اتصال)
- 2
- عدم امکان اتصال به PipeWire
- 3
- خطای مختص به دستور (مانند پیدا نشدن شیء)
مثال‌ها (EXAMPLES)
نمایش وضعیت سیستم:
wpctl status
تنظیم سینک صوتی پیش‌فرض:
wpctl set-default 42
تنظیم بلندی صدا روی 75% در سینک پیش‌فرض:
wpctl set-volume @DEFAULT_SINK@ 75%
افزایش بلندی صدا به میزان 5% در یک گره مشخص:
wpctl set-volume 42 5%+
بی‌صدا کردن منبع پیش‌فرض:
wpctl set-mute @DEFAULT_SOURCE@ 1
تغییر وضعیت بی‌صدا در سینک پیش‌فرض:
wpctl set-mute @DEFAULT_SINK@ toggle
بررسی یک دستگاه به همراه اشیای مرتبط:
wpctl inspect --associated 30
نمایش تمام تنظیمات WirePlumber:
wpctl settings
اعمال یک تنظیم مشخص:
wpctl settings bluetooth.autoswitch true
ذخیرهٔ تمام تنظیمات فعلی:
wpctl settings --save
تنظیم سطح لاگ WirePlumber روی debug:
wpctl set-log-level D
تنظیم سطح لاگ برای یک کلاینت مشخص:
wpctl set-log-level 42 W
فهرست کردن تمام سینک‌های صوتی:
wpctl list audio sinks
بازنشانی وضعیت WirePlumber (اجرای آزمایشی):
wpctl reset --dry-run
بازنشانی وضعیت و پیکربندی WirePlumber بدون درخواست تأیید:
wpctl reset --wireplumber-config --yes
wpctl reset --all
نکات (NOTES)
شناسه‌های اشیاء را می‌توان با استفاده از دستور status پیدا کرد. نمایش سلسله‌مراتبی، شناسه‌ها را برای دستگاه‌ها، گره‌ها و سایر اشیاء نشان می‌دهد.
مقادیر بلندی صدا، اعدادی با ممیز شناور هستند که در آن‌ها 1.0 بیانگر ۱۰۰٪ بلندی صدا است. این مقادیر می‌توانند برای اعمال تقویت صدا (amplification) از 1.0 فراتر روند.
هنگام استفاده از گزینهٔ --pid، دستور wpctl تمام گره‌های صوتی مرتبط با شناسهٔ فرایند مشخص‌شده را پیدا کرده و عملیات را روی همهٔ آن‌ها اعمال می‌کند.
همچنین ببینید (SEE ALSO)
wireplumber(1), wpexec(1), pipewire(1), pw-cli(1), pw-dump(1)
مستندات WirePlumber: https://pipewire.pages.freedesktop.org/wireplumber
نویسندگان (AUTHORS)
توسعه‌دهندگان WirePlumber
کپی‌رایت و تکثیر (COPYRIGHT)
2020-2025, Collabora & contributors
| September 3, 2026 | 0.5.17 |