نام (NAME)

pipewire.conf - فایل پیکربندی سرور PipeWire

توضیحات (DESCRIPTION)

فایل پیکربندی سرور PipeWire

خلاصه دستور (SYNOPSIS)

$XDG_CONFIG_HOME/pipewire/pipewire.conf

/etc/pipewire/pipewire.conf

/usr/share/pipewire/pipewire.conf

/usr/share/pipewire/pipewire.conf.d/

/etc/pipewire/pipewire.conf.d/

$XDG_CONFIG_HOME/pipewire/pipewire.conf.d/

توضیحات (DESCRIPTION)

پایپ‌ویر (PipeWire) سرویسی است که اشتراک‌گذاری محتوای چندرسانه‌ای را بین دستگاه‌ها و برنامه‌ها تسهیل می‌کند.

دیمن در هنگام راه‌اندازی، یک فایل پیکربندی اصلی را برای پیکربندی خود می‌خواند. این دیمن مجموعه‌ای از دستورات فهرست‌شده در فایل پیکربندی را اجرا می‌کند.

فایل پیکربندی به ترتیبی که در بخش خلاصه دستور (SYNOPSIS) آمده است، جستجو می‌شود. از متغیرهای محیطی PIPEWIRE_CONFIG_DIR، PIPEWIRE_CONFIG_PREFIX و PIPEWIRE_CONFIG_NAME می‌توان به ترتیب برای تعیین شاخه، زیرشاخه و فایل پیکربندی جایگزین استفاده کرد.

سایر فایل‌های پیکربندی PipeWire عموماً از همین منطق جستجو پیروی می‌کنند و نام فایل پیکربندی مربوطه جایگزین pipewire.conf می‌شود.

فایل‌های پیکربندی الحاقی (DROP-IN CONFIGURATION FILES)

تمام فایل‌های *.conf در شاخه‌های pipewire.conf.d/ بارگذاری و در پیکربندی ادغام می‌شوند. بخش‌های واژه‌نامه‌ای (Dictionary) ادغام شده و ویژگی‌ها را در صورت وجود بازنویسی می‌کنند، و به بخش‌های آرایه‌ای (Array) افزوده می‌شود. فایل‌های الحاقی (Drop-in) همان قالب فایل پیکربندی اصلی را دارند، اما فقط شامل تنظیماتی هستند که باید تغییر داده شوند.

از آنجا که فایل پیکربندی pipewire.conf شامل بخش‌های گوناگونی است که باید برای عملکرد صحیح وجود داشته باشند، استفاده از فایل‌های الحاقی برای پیکربندی توصیه می‌شود.

# ~/.config/pipewire/pipewire.conf.d/custom.conf
context.properties = {
    default.clock.min-quantum = 128
}

قالب فایل پیکربندی (CONFIGURATION FILE FORMAT)

فایل پیکربندی در قالب JSON نوع "SPA" است.

فایل پیکربندی شامل کلیدهای سطح بالا (Top-level) است که همان بخش‌ها هستند. مقدار هر بخش یا یک واژه‌نامه (Dictionary)، { }، یا یک آرایه (Array)، [ ] است. اعلان بخش‌ها و آیتم‌های واژه‌نامه به صورت KEY = VALUE بوده و با فاصله از یکدیگر جدا می‌شوند. برای مثال:

context.properties = {  # top-level dictionary section
    key1 = value  # a simple value
    key2 = { key1 = value1 key2 = value2 }  # a dictionary with two entries
    key3 = [ value1 value2 ]  # an array with two entries
    key4 = [ { k = v1 } { k = v2 } ]  # an array of dictionaries
}
context.modules = [  # top-level array section
    value1
    value2
]

فایل‌های پیکربندی را می‌توان با نحو استاندارد JSON نیز نوشت، اما برای ویرایش دستی آسان‌تر، نگارش آسان‌گیر "SPA" مجاز است. در JSON نوع "SPA":

• کاراکتر : برای جداسازی کلیدها و مقادیر می‌تواند با = یا یک فاصله جایگزین شود.
• علامت " در اطراف کلیدها و رشته‌ها تا زمانی که از نویسه‌های خاص در رشته‌ها استفاده نشده باشد، می‌تواند حذف شود.
• کاراکتر , برای جداسازی اشیاء می‌تواند با یک نویسه فاصله (whitespace) جایگزین شود.
• از # می‌توان برای شروع یک یادداشت (کامنت) تا انتهای خط استفاده کرد.

بخش‌های فایل پیکربندی (CONFIGURATION FILE SECTIONS)

context.properties

context.spa-libs

context.modules

context.objects

context.exec

node.rules

device.rules

ویژگی‌های زمینه (CONTEXT PROPERTIES)

ویژگی‌های موجود PipeWire در context.properties و مقادیر پیش‌فرض احتمالی آن‌ها.

clock.power-of-two-quantum = true

context.data-loop.library.name.system

loop.rt-prio = -1

loop.class = [ data.rt .. ]

context.num-data-loops = 1

context.data-loops = [ ... ]

# ~/.config/pipewire/pipewire.conf.d/custom.conf
context.data-loops = [
    {
         #library.name.system = support/libspa-support
         loop.rt-prio = -1
         loop.class = [ data.rt .. ]
         thread.name = data-loop.0
         thread.affinity = [ 0 1 ]
    }
    ...
]

core.daemon = false

core.name = pipewire-0

cpu.zero.denormals = false

cpu.vm.name = null

default.clock.rate = 48000

default.clock.allowed-rates = [ ]

default.clock.min-quantum = 32

default.clock.max-quantum = 8192

default.clock.quantum = 1024

default.clock.quantum-limit = 8192

default.clock.quantum-floor = 4

default.video.width

default.video.height

default.video.rate.num

default.video.rate.denom

library.name.system = support/libspa-support

link.max-buffers = 64

log.level = 2

mem.allow-mlock = true

mem.warn-mlock = false

mem.mlock-all = false

rlimit.nofile = 4096

rlimit.*resource* = value

settings.check-quantum = false

settings.check-rate = false

support.dbus = true

vm.overrides = { default.clock.min-quantum = 1024 }

context.modules.allow-empty = false

ویژگی‌های زمینه ممکن است شامل مقادیر سفارشی نیز باشند. برای مثال، بخش‌های context.modules و context.objects می‌توانند شرایط اضافی را تعریف کنند که کنترل می‌کند آیا یک ماژول یا شیء بسته به ویژگی‌های موجود بارگذاری شود یا خیر.

کتابخانه‌های SPA (SPA LIBRARIES)

افزونه‌های SPA بر اساس نام کارخانه (factory-name) بارگذاری می‌شوند. این یک نام شناخته‌شده است که ویژگی‌هایی را که افزونه باید داشته باشد به طور منحصربه‌فرد توصیف می‌کند. بخش context.spa-libs نگاشتی بین factory-name و افزونه‌ای که کارخانه در آن یافت می‌شود فراهم می‌کند.

نام‌های کارخانه می‌توانند شامل نویسه عام (Wildcard) باشند تا چندین کارخانه مرتبط را در یک افزونه گروه‌بندی کنند. افزونه از اولین factory-name تطبیق‌یافته بارگذاری می‌شود.

# ~/.config/pipewire/pipewire.conf.d/custom.conf
context.spa-libs = {
    audio.convert.* = audioconvert/libspa-audioconvert
    avb.*           = avb/libspa-avb
    api.alsa.*      = alsa/libspa-alsa
    api.v4l2.*      = v4l2/libspa-v4l2
    api.libcamera.* = libcamera/libspa-libcamera
    api.bluez5.*    = bluez5/libspa-bluez5
    api.vulkan.*    = vulkan/libspa-vulkan
    api.jack.*      = jack/libspa-jack
    support.*       = support/libspa-support
    video.convert.* = videoconvert/libspa-videoconvert
}

ماژول‌ها (MODULES)

ماژول‌های PipeWire برای بارگذاری. libpipewire-modules(7) را ببینید.

# ~/.config/pipewire/pipewire.conf.d/custom.conf
context.modules = [
    #{ name = MODULENAME
    #    ( args  = { KEY = VALUE ... } )
    #    ( flags = [ ( ifexists ) ( nofail ) ] )
    #    ( condition = [ { KEY = VALUE ... } ... ] )
    #}
    #
]

name

args = { }

flags = [ ]

condition = [ ]

اشیاء زمینه (CONTEXT OBJECTS)

بخش context.objects به شما امکان می‌دهد اشیائی را از کارخانه‌ها بسازید (که معمولاً با بارگذاری ماژول‌ها در context.modules ایجاد می‌شوند).

# ~/.config/pipewire/pipewire.conf.d/custom.conf
context.objects = [
    #{ factory = <factory-name>
    #    ( args  = { <key> = <value> ... } )
    #    ( flags = [ ( nofail ) ] )
    #    ( condition = [ { <key> = <value> ... } ... ] )
    #}
]

این بخش می‌تواند برای ساخت گره‌ها یا پیوندها میان گره‌ها استفاده شود.

factory

args = { }

flags = [ ]

condition = [ ]

# ~/.config/pipewire/pipewire.conf.d/custom.conf
context.objects = [
    { factory = spa-node-factory
      args = {
          factory.name    = support.node.driver
          node.name       = Dummy-Driver
          node.group      = pipewire.dummy
          priority.driver = 20000
      },
      condition = [ { core.daemon = true } ]
    }
]

اجرای دستور (COMMAND EXECUTION)

از بخش context.exec می‌توان برای اجرای دستورات دلخواه به عنوان بخشی از مقداردهی اولیه برنامه PipeWire استفاده کرد.

# ~/.config/pipewire/pipewire.conf.d/custom.conf
context.exec = [
    #{   path = <program-name>
    #    ( args = "<arguments>" | [ <arg1> <arg2> ... ] )
    #    ( condition = [ { <key> = <value> ... } ... ] )
    #}
]

path

args

condition

# ~/.config/pipewire/pipewire.conf.d/custom.conf
context.exec = [
    { path = "pactl" args = "load-module module-always-sink" }
]

قواعد تطبیق (MATCH RULES)

برخی از بخش‌های فایل پیکربندی شامل قواعد تطبیق هستند. این امکان را فراهم می‌کند که هنگام ایجاد یا به‌روزرسانی شیئی (معمولاً یک گره یا جریان) که با ویژگی‌های خاصی مطابقت دارد، عملیاتی انجام شود.

شیء کلی قواعد از الگوی زیر پیروی می‌کند:

<rules> = [
    {
        matches = [
            # هر یک از مجموعه‌های ویژگی زیر مطابقت داده می‌شوند،
            # اگر هر کدام تطبیق پیدا کند، عملیات‌ها اجرا می‌شوند
            {
                # <key> = <value>
                # تمام کلیدها باید با مقدار تطبیق داشته باشند. ! نفی می‌کند. ~ آغاز عبارت منظم است.
                #application.process.binary = "teams"
                #application.name = "~speech-dispatcher.*"
                # نبود ویژگی می‌تواند با مقایسه با null آزمایش شود
                #pipewire.sec.flatpak = null
            }
            {
                # تطبیق‌های بیشتر در اینجا...
            }
            ...
        ]
        actions = {
            <action-name> = <action value>
            ...
        }
    }
]

قواعد تطبیق یک آرایه از قواعد هستند.

یک قاعده همواره یک شیء JSON با دو کلید است: matches و actions. کلید matches برای تعریف شرایطی که باید برقرار شوند تا قاعده true ارزیابی شود به کار می‌رود، و کلید actions برای تعریف عملیاتی که در صورت ارزیابی قاعده به true انجام می‌شوند استفاده می‌گردد.

کلید matches همواره یک آرایه JSON از اشیاء است که در آن هر شیء شرطی را تعریف می‌کند که باید برقرار شود. هر شرط فهرستی از جفت‌های کلید-مقدار است که در آن کلید، نام ویژگی مورد تطبیق است و مقدار، مقداری است که ویژگی باید داشته باشد. در داخل یک شرط، تمام جفت‌های کلید-مقدار با AND منطقی با یکدیگر ترکیب می‌شوند، و تمام شرایط در آرایه matches با OR منطقی ترکیب می‌گردند.

کلید actions همواره یک شیء JSON است که در آن هر جفت کلید-مقدار، عملیاتی را تعریف می‌کند که هنگام ارزیابی قاعده به true انجام می‌شود. نام عملیات مخصوص آن قاعده است و توسط مستندات قاعده تعریف می‌شود، اما در بیشتر موارد عملیات update-props را مشاهده خواهید کرد که برای به‌روزرسانی ویژگی‌های شیء تطبیق‌یافته استفاده می‌شود.

در آرایه matches، استفاده از عبارات منظم (Regular expressions) برای تطبیق مقادیر ویژگی‌ها نیز امکان‌پذیر است. برای مثال، برای تطبیق تمام گره‌هایی که نام آن‌ها با my_ شروع می‌شود، می‌توانید از شرط زیر استفاده کنید:

matches = [
  {
    node.name = "~my_.*"
  }
]

نویسه ~ نشان می‌دهد که مقدار یک عبارت منظم است. نحو دقیق عبارات منظم، نحو عبارات منظم توسعه‌یافته POSIX است، همان‌طور که در صفحه راهنمای regex (7) شرح داده شده است.

علاوه بر عبارات منظم، می‌توانید از نویسه ! برای نفی یک شرط نیز استفاده کنید. برای مثال، برای تطبیق تمام گره‌هایی که نام آن‌ها با my_ شروع نمی‌شود، می‌توانید از شرط زیر استفاده کنید:

matches = [
  {
    node.name = "!~my_.*"
  }
]

نویسه ! را می‌توان با یا بدون عبارت منظم استفاده کرد. برای مثال، برای تطبیق تمام گره‌هایی که نام آن‌ها برابر با my_node نیست، می‌توانید از شرط زیر استفاده کنید:

matches = [
  {
    node.name = "!my_node"
  }
]

مقدار null معنای خاصی دارد؛ این مقدار بررسی می‌کند که آیا ویژگی در دسترس نیست (یا تنظیم نشده است). برای بررسی اینکه آیا یک ویژگی تنظیم نشده است:

matches = [
  {
    node.name = null
  }
]

برای بررسی وجود یک ویژگی، می‌توان از شرط !null استفاده کرد، برای مثال:

matches = [
  {
    node.name = "!null"
  }
  {
    node.name = !null            # نحو ساده‌شده
  }
]

برای کار با رشته "null"، باید رشته را گریزدهی (Escape) کرد. برای مثال، برای بررسی اینکه آیا یک ویژگی مقدار رشته‌ای "null" دارد، از عبارت زیر استفاده کنید:

matches = [
  {
    node.name = "null"
  }
]

برای کار با هر مقداری به جز رشته "null"، از عبارت زیر استفاده کنید:

matches = [
  {
    node.name = "!\"null\""
  }
  {
    node.name = !"null"      # نحو ساده‌شده
  }
]

قواعد ویژگی‌های زمینه (CONTEXT PROPERTIES RULES)

از context.properties.rules می‌توان برای به‌روزرسانی پویای ویژگی‌ها بر اساس سایر ویژگی‌ها استفاده کرد.

یک حالت متداول، به‌روزرسانی تنظیمات سفارشی در هنگام اجرا درون یک ماشین مجازی (VM) است. مقدار cpu.vm.name هنگام اجرا در یک ماشین مجازی به طور خودکار با نام VM تنظیم می‌شود. می‌توان یک قاعده تطبیق برای تنظیم ویژگی‌های سفارشی به این صورت نوشت:

# ~/.config/pipewire/pipewire.conf.d/custom.conf
context.properties.rules = [
    {   matches = [ { cpu.vm.name = !null } ]
        actions = {
            update-props = {
                # این بازنویسی‌ها فقط هنگام اجرا در یک ماشین مجازی اعمال می‌شوند.
                default.clock.min-quantum = 1024
            }
        }
    }
}

قواعد گره (NODE RULES)

گزینه node.rules هر بار که ویژگی‌های یک گره تنظیم یا به‌روزرسانی می‌شوند ارزیابی می‌گردد. این ویژگی را می‌توان در سمت سرور برای بازنویسی ویژگی‌های تنظیم‌شده توسط کلاینت روی گره‌های دلخواه استفاده کرد.

بخش node.rules یک عملیات update-props فراهم می‌کند که شیئی شامل ویژگی‌هایی که باید روی شیء گره به‌روزرسانی شوند را دریافت می‌کند.

یک بخش node.rules را مانند زیر به فایل پیکربندی اضافه کنید:

# ~/.config/pipewire/pipewire.conf.d/custom.conf
node.rules = [
    {
        matches = [
            {
                # تمام کلیدها باید با مقدار تطبیق داشته باشند. ! نفی می‌کند. ~ آغاز عبارت منظم است.
                client.name = "jack_simple_client"
            }
        ]
        actions = {
            update-props = {
                node.force-quantum = 512
            }
        }
    }
]

این کار ویژگی node.force-quantum مربوط به jack_simple_client را به 512 تنظیم می‌کند.

قواعد دستگاه (DEVICE RULES)

گزینه device.rules هر بار که ویژگی‌های یک دستگاه تنظیم یا به‌روزرسانی می‌شوند ارزیابی می‌گردد. این ویژگی را می‌توان در سمت سرور برای بازنویسی ویژگی‌های تنظیم‌شده توسط کلاینت روی دستگاه‌های دلخواه استفاده کرد.

بخش device.rules یک عملیات update-props فراهم می‌کند که شیئی شامل ویژگی‌هایی که باید روی شیء دستگاه به‌روزرسانی شوند را دریافت می‌کند.

یک بخش device.rules را مانند زیر به فایل پیکربندی اضافه کنید:

# ~/.config/pipewire/pipewire.conf.d/custom.conf
device.rules = [
    {
        matches = [
            {
                # تمام کلیدها باید با مقدار تطبیق داشته باشند. ! نفی می‌کند. ~ آغاز عبارت منظم است.
                device.name = ""v4l2_device.pci-0000_00_14.0-usb-0_1.2_1.0
            }
        ]
        actions = {
            update-props = {
                device.description = "My Webcam"
            }
        }
    }
]

این کار ویژگی device.description دستگاه با device.name داده‌شده را به "My Webcam" تنظیم می‌کند.

نویسندگان (AUTHORS)

توسعه‌دهندگان پایپ‌ویر (The PipeWire Developers) https://gitlab.freedesktop.org/pipewire/pipewire/issues؛ پایپ‌ویر در https://pipewire.org در دسترس است.

همچنین ببینید (SEE ALSO)

pipewire(1), pw-mon(1), libpipewire-modules(7) pipewire-pulse.conf(5) pipewire-client.conf(5)