.Dd September 21, 2021
.Dt PLAYERCTL 1
.Os
.Sh "نام (NAME)"
.Nm playerctl
.Nd کنترل پخش‌کننده‌های چندرسانه‌ای از طریق MPRIS
.Sh "خلاصه دستور (SYNOPSIS)"
.Nm
.Op Fl aFhlV
.Op Fl f Ar FORMAT
.Op Fl i Ar NAME
.Op Fl p Ar NAME
.Cm command
.Sh "توضیحات (DESCRIPTION)"
ابزار
.Nm
پخش‌کننده‌های چندرسانه‌ای دارای قابلیت MPRIS را کنترل می‌کند.
علاوه بر ارائهٔ امکان کنترل پخش، مکث و توقف،
.Nm
همچنین از رفتن به قطعهٔ قبلی و بعدی،
قابلیت جست‌وجو به جلو و عقب در قطعه،
و کنترل میزان صدا پشتیبانی می‌کند.
.Nm
همچنین از نمایش متاداده
.Pq مانند هنرمند، عنوان، آلبوم
برای قطعهٔ کنونی،
و نمایش وضعیت پخش‌کننده پشتیبانی می‌کند.
.Pp
پخش‌کننده‌هایی که می‌توان با استفاده از
.Nm
آن‌ها را کنترل کرد شامل
.Xr audacious 1 ،
.Xr cmus 1 ،
.Xr mopidy 1 ،
.Xr mpd 1 ،
.Xr quodlibet 1 ،
.Xr rhythmbox 1 ،
.Xr vlc 1
و
.Xr xmms2 1
می‌شوند.
با این حال،
هر پخش‌کننده‌ای که مشخصات واسط MPRIS را پیاده‌سازی کند،
از جمله مرورگرهای وب،
می‌تواند با استفاده از
.Nm
کنترل شود.
.Pp
همچنین Playerctl به همراه یک دیمِن به نام
.Nm playerctld
ارائه می‌شود که فعالیت‌های پخش‌کننده‌های چندرسانه‌ای را رهگیری می‌کند. هنگامی که
.Nm playerctld
در حال اجرا باشد، دستورهای
.Nm
بر روی پخش‌کننده‌ای با جدیدترین فعالیت عمل خواهند کرد.
برای راه‌اندازی دیمِن، دستور
.Nm playerctld daemon
را اجرا کنید.
.Pp
گزینه‌ها به شرح زیر هستند:
.Bl -tag -width Ds
.It Fl a , -all-players
اعمال دستور بر روی تمام پخش‌کننده‌های در دسترس.
.It Fl F , -follow
مسدود کردن فرایند و چاپ پرس‌وجوی به‌روزشده هنگام تغییر آن.
.It Fl f Ar FORMAT , Fl -format Ar FORMAT
تنظیم خروجی دستور جاری به
.Ar FORMAT .
بخش
.Sx Format Strings
را ببینید.
.It Fl h , -help
چاپ این راهنما و سپس خروج.
.It Fl i Ar NAME , Fl -ignore-player Ar NAME
نادیده گرفتن پخش‌کنندهٔ مشخص
.Ar NAME .
می‌توان چندین پخش‌کننده را در یک فهرستِ جداشده با ویرگول مشخص کرد.
.It Fl l , -list-all
فهرست کردن نام‌های پخش‌کننده‌های در حال اجرایی که قابل کنترل هستند.
.It Fl p Ar NAME , Fl -player Ar NAME
کنترل پخش‌کنندهٔ مشخص
.Ar NAME .
می‌توان چندین پخش‌کننده را در یک فهرستِ جداشده با ویرگول مشخص کرد.
پیش‌فرض بر روی اولین پخش‌کنندهٔ در دسترس است.
نام "name" هم با "name" و هم با "name.{INSTANCE}" مطابقت دارد.
علاوه بر این، نام "%any" با هر پخش‌کننده‌ای مطابقت دارد.
.It Fl s, -no-messages
بی‌صدا کردن برخی از پیام‌های عیب‌یابی و خطا.
.It Fl V , -version
چاپ شماره نسخه و سپس خروج.
.El
.Pp
دستورها به شرح زیر هستند:
.Bl -tag -width Ds
.It Cm status
دریافت وضعیت جاری پخش‌کننده.
.It Cm play
دستور به پخش‌کننده برای پخش.
.It Cm pause
دستور به پخش‌کننده برای مکث.
.It Cm play-pause
دستور به پخش‌کننده برای جابه‌جایی متناوب میان پخش و مکث.
.It Cm stop
دستور به پخش‌کننده برای توقف.
.It Cm next
دستور به پخش‌کننده برای رفتن به قطعهٔ بعدی.
.It Cm previous
دستور به پخش‌کننده برای رفتن به قطعهٔ قبلی.
.It Cm position Op Ar OFFSET Ns Op Ar + Ns | Ns Ar -
چاپ موقعیت قطعهٔ جاری بر حسب ثانیه.
در صورت مشخص شدن
.Ar OFFSET ،
موقعیت به
.Ar OFFSET
ثانیه از آغاز قطعهٔ جاری تغییر می‌یابد.
با افزودن آرگومان اختیاری
.Op Ar + Ns | Ns Ar -
به انتهای آن،
موقعیت به اندازهٔ
.Ar OFFSET
ثانیه نسبت به موقعیت جاری به جلو یا عقب جابه‌جا می‌شود.
.It Cm volume Op Ar LEVEL Ns Op + Ns | Ns Ar -
چاپ میزان صدای پخش‌کننده در مقیاس 0.0
.Pq 0%
تا 1.0
.Pq 100% .
در صورت مشخص شدن
.Ar LEVEL ،
میزان صدای پخش‌کننده روی
.Ar LEVEL
تنظیم می‌شود.
با افزودن آرگومان اختیاری
.Op Ar + Ns | Ns Ar -
به انتهای آن،
میزان صدای پخش‌کننده به اندازهٔ
.Ar LEVEL
افزایش یا کاهش می‌یابد.
.It Cm metadata Op Ar KEY
چاپ تمام مشخصه‌های متاداده برای قطعهٔ جاری که توسط پخش‌کنندهٔ کنونی تعیین شده‌اند.
اگر
.Ar KEY
مشخص شده باشد، تنها مقدار
.Ar KEY
چاپ می‌شود.
.It Cm open Ar URI
باز کردن
.Ar URI
در پخش‌کننده.
.Ar URI
می‌تواند نام یک فایل یا یک URL خارجی باشد.
.It Cm shuffle Op Ic On | Off | Toggle
چاپ وضعیت پخش تصادفی (shuffle) پخش‌کننده.
در صورت مشخص کردن وضعیت،
وضعیت پخش تصادفی روی یکی از مقادیر
.Ic On
،
.Ic Off
یا
.Ic Toggle
تنظیم می‌شود.
.It Cm loop Op Ic None | Track | Playlist
چاپ وضعیت تکرار (loop) پخش‌کننده.
در صورت مشخص کردن وضعیت،
وضعیت تکرار روی
.Ic None
.Pq غیرفعال کردن تکرار ،
.Ic Track
.Pq تکرار قطعهٔ جاری ،
یا
.Ic Playlist
.Pq تکرار فهرست پخش جاری
تنظیم می‌شود.
.El.Ss رشته‌های قالب‌بندی (Format Strings)
خروجی دستورهای
.Cm position ،
.Cm metadata ،
.Cm status
و
.Cm volume
را می‌توان با استفاده از یک رشته قالب‌بندی کنترل کرد.
متغیرهای مقداردهی‌شده توسط این دستورها را می‌توان با قرار دادن درون آکولاد در رشته قالب گنجاند:
.Ql Brq Brq Va var .
سپس این متغیرها در خروجی بسط خواهند یافت.
.Pp
هر دستور به متغیرهای زیر دسترسی دارد:
.Bl -tag -width Ds
.It Va playerName
نام پخش‌کننده کنونی.
.It Va position
موقعیت زمانی قطعه کنونی،
بر حسب میکروثانیه.
.It Va status
وضعیت پخش‌کننده کنونی.
.It Va volume
میزان صدای پخش‌کننده، مقیاس‌بندی‌شده از 0.0
.Pq 0%
تا 1.0
.Pq 100% .
.El
.Pp
هر یک از ویژگی‌های فهرست‌شده در دستور
.Cm metadata
نیز به عنوان متغیر مقداردهی می‌شوند.
توصیه می‌شود این فهرست برای هر پخش‌کننده بررسی شود،
زیرا ممکن است پخش‌کننده‌های مختلف ویژگی‌های یکسانی را تنظیم نکنند.
برای مشاهده فهرستی از تمام ویژگی‌ها در مشخصات MPRIS، به
.%T MPRIS v2 metadata guidelines
مراجعه کنید.
رایج‌ترین ویژگی‌ها به شرح زیرند:
.Bl -tag -width Ds
.It Va album , xesam:album
آلبوم قطعه کنونی.
.It Va artist , xesam:artist
هنرمند قطعه کنونی.
.It Va title , xesam:title
عنوان قطعه کنونی.
.El
.Pp
توابع کمکی نیز برای تبدیل متغیرهای بسط‌یافته به دیگر نمایش‌ها در دسترس هستند.
آن‌ها به صورت
.Ql Brq Brq Fn func var
فراخوانی می‌شوند.
توابع کمکی به شرح زیر هستند:
.Bl -tag -width Ds
.It Fn lc str
تبدیل رشته
.Va str
به حروف کوچک.
.It Fn uc str
تبدیل رشته
.Va str
به حروف بزرگ.
.It Fn markup_escape str
گریز دادن (escape) نویسه‌های XML در رشته
.Va str .
.It Fn default str1 str2
چاپ
.Fa str1
در صورت تنظیم بودن، وگرنه چاپ
.Fa str2 .
.It Fn duration time
قالب‌بندی مجدد برچسب زمانی میکروثانیه‌ای
.Va time
به شکل
.Ql hh:mm:ss .
تنها با
.Va position
یا
.Va mpris:length
قابل فراخوانی است.
.It Fn emoji key
تلاش برای تبدیل مقدار
.Fa key
به یک ایموجی متناظر. در حال حاضر برای
.Fa status
و
.Fa volume
پیاده‌سازی شده است.
.It Fn trunc str len
کوتاه کردن
.Fa str
تا حداکثر
.Fa len
نویسه، با افزودن علامت سه‌نقطه (…) در صورت لزوم.
.El
.Pp
زبان قالب‌بندی همچنین قادر به انجام محاسبات پایه‌ای ریاضی است.
.Pp
ارجاع به توابع ناشناخته باعث خروج
.Nm
همراه با خطا خواهد شد.
ارجاع به متغیرهای ناشناخته به رشته‌های خالی بسط داده می‌شود.
متنی که درون آکولاد قرار نگرفته باشد، عیناً چاپ خواهد شد..Sh "وضعیت خروج (EXIT STATUS)"
.Ex -std
.Sh "مثال‌ها (EXAMPLES)"
نمایش نام پخش‌کننده،
وضعیت پخش با حروف کوچک،
و موقعیت زمانی و مدت‌زمان در قالبی خوانا برای انسان:
.Bd -literal -offset indent
$ playerctl metadata --format '{{playerName}}: {{lc(status)}} '\e
\&'{{duration(position)}}|{{duration(mpris:length)}}'
.Ed
.Sh "همچنین ببینید (SEE ALSO)"
.Rs
.%T MPRIS v2 metadata guidelines
.%D 18 سپتامبر 2013
.%I freedesktop.org
.%U https://freedesktop.org/wiki/Specifications/mpris-spec/metadata
.Re
.Pp
.Lk https://github.com/altdesktop/playerctl "صفحه اصلی playerctl" ,
.Lk https://dubstepdish.com/playerctl "مستندات API دستور playerctl" ,
.Lk https://wiki.gnome.org/Projects/GObjectIntrospection/Users \
    "انقیادهای زبانی GObject introspection"
.Sh "نویسندگان (AUTHORS)"
.An -nosplit
ابزار
.Nm
توسط
.An Tony Crisci Aq Mt tony@dubstepdish.com
نگهداری می‌شود
و تحت مجوز GNU Lesser General Public License 3.0 در دسترس قرار گرفته است.
.Pp
این مرجع توسط
.An Nick Morrott Aq Mt knowledgejunkie@gmail.com
برای پروژه Debian GNU/Linux نوشته شده است.
این راهنما بعداً توسط
.An Stephen Gregoratto Aq Mt dev@sgregoratto.me
به‌روزرسانی و گسترش یافت.