Özellikler

Sound (fx-sound)

Telefonun ve Music uygulamasının kullandığı, paketle gelen 3D ses resource'u; ayarları ve tam export başvurusu.

#Nedir

fx-sound, bağımsız bir 3D ses altyapısıdır. Web sesini gizli bir NUI sayfası içinde Web Audio API ile çalar; böylece bir ses dünyada konumlandırılabilir ve filtrelenebilir: kapalı bir araç, iç mekân ya da su için low-pass boğukluk, bass boost ve ses başına parametrik EQ.

Bir telefon uygulaması değildir ve simgesi yoktur. FX Phone onu yakındaki oyuncuların duyabildiği zil ve bildirim seslerini çalmak için kullanır; fx-musicapp da ses altyapısı olarak kullanır.

#Gereksinimler

Gereksinim Neden
Client internet erişimi Medya, verdiğin URL'lerden stream edilir
HTTPS medya URL'leri NUI sayfası https'tir; düz http kaynakları engellenir ya da yükseltilir
youtube.com erişimi Yalnızca YouTube bağlantıları çalındığında
Server'dan dışa giden HTTP Yalnızca Sound.VersionCheck açıkken, güncelleme bildirimi için

Framework gereksinimi, veritabanı, item ya da başka bir resource'a bağımlılık yoktur.

#Kurulum

Ses çalmak için onu kullanan her resource'tan önce başlat:

cfgensure fx-sound

#Telefon onu nasıl kullanır

fx-sound telefona hiçbir şey kaydetmez. FX Phone onu çalışma sırasında arar:

  • configs/config_sound.lua içindeki Config.Sound.Resource ses altyapısını seçer: auto, fx-sound, xsound veya none. auto olduğunda, başlatılmışsa fx-sound kullanılır.
  • Config.Sound.Enable3D, Range ve BystanderVolume, yakındaki oyuncuların başka bir telefonu duyup duymayacağını ve nasıl duyacağını belirler.
  • Yakındaki oyuncuların duyduğu zil ve bildirim sesleri PlayPos ile çalınır, SetPosition ile taşınır, SetVolume ile kısılır ve Stop ile bitirilir.

Onu kullanan resource'lar dependencies{} içine eklemek yerine aynı şekilde algılamalıdır, çünkü bağımsız olarak durdurulabilir:

luaif GetResourceState('fx-sound') ~= 'started' then return end

#Öne çıkan config ayarları

Bütün ayarlar config.lua içindedir. Başlangıçta NUI sayfasına gönderilir, bu yüzden değişiklikler resource'un yeniden başlatılmasını gerektirir.

Anahtar Varsayılan Anlamı
Sound.Debug false Parça sonu, hata ve buffer takılmasını F8'e loglar
Sound.VersionCheck true Başlangıçta server konsoluna bir güncelleme bildirimi
Sound.BassFreq, Sound.Bass 120.0, 0 / 3 / 6 / 9 dB SetMasterEQ'nun kullandığı bass boost hazır ayarları
Sound.Env none 20000, car_closed 400, interior 1500, water 350 Ortam başına Hz cinsinden boğukluk kesim frekansı. Düşük değer daha boğuktur
Sound.Panning 'equalpower' 'HRTF' daha hassas ama daha ağırdır
Sound.DistanceModel 'inverse' linear, inverse veya exponential
Sound.RefDistance 3.0 Mesafeyle azalma başlamadan önce tam ses düzeyindeki metre
Sound.RolloffFactor 1.0 Bir 3D sesin RefDistance'ın ötesinde ne kadar hızlı azaldığı
Sound.SumNormalize 0.85 Çok noktalı bir sesin toplam düzeyini geri çeker. 1.0 tam telafi, 0.0 kapalıdır
Sound.EqBandsMax 12 Bir sesteki en fazla EQ bandı
Sound.EqSmoothing 0.05 Bir EQ değerinin kaç saniyede yumuşakça geçtiği; 0 kapalıdır
Sound.PosSmoothing, Sound.RotSmoothing, Sound.EnvSmoothing 0.05, 0.12, 0.15 Konum, yön ve boğukluk değişiklikleri için saniye cinsinden geçiş süreleri
Sound.ProgressMs 500 Sayfanın çalma konumunu Lua'ya ne sıklıkla bildirdiği
Sound.RetryCount, Sound.RetryDelayMs 2, 400 Çalmadan önce başarısız olan bir parça için ek denemeler
Sound.YouTubeApiTimeoutMs 15000 YouTube'un oynatıcı script'i için ne kadar bekleneceği
Sound.IdleRecycleMs 30000 Duraklatılmış bir YouTube sesi bu süreden sonra, konumu saklanarak kaldırılır. 0 hiçbir zaman demektir
Sound.YouTubeMax 4 Bir client'ın aynı anda çalıştırabileceği YouTube oynatıcısı sayısı. Sınır aşılınca en sessiz olan temizlenir ve sesi yükseldiğinde geri gelir. 0 sınırsızdır
Sound.YouTubeReviveVolume 0.03 Temizlenmiş bir sesin kendini yeniden kurduğu ses düzeyi
Sound.SwapMargin 0.05 Yeni gelenin mevcut bir oynatıcının yerini alması için ne kadar daha yüksek olması gerektiği
Sound.ReviveDelayMs 4000 Temizlenen bir oynatıcının en az ne kadar süre kaldırılmış kalacağı

#Kurallar

Terim Anlamı
id Seçtiğin herhangi bir string. Sonraki her şey için tanıtıcıdır. Var olan bir id ile Play ya da PlayPos çağırmak, altındaki sesi değiştirir. Id'lerine önek ekle, örneğin myjob:radio:1
url https olmalıdır. YouTube bağlantısı da kabul edilir
volume 0.0 ile 1.0 arası. Aralık dışındaki değerler sınırlara çekilir
coords Bir vector3, adlandırılmış alanlı bir { x, y, z } tablosu ya da bir { 1, 2, 3 } dizisi
env Sound.Env'in bir anahtarı: none, car_closed, interior, water
distance Metre cinsinden en fazla duyulma mesafesi

Bütün ses export'ları client tarafındadır. GetVersionStatus server tarafındadır. Net event'i ya da komut yoktur.

#Dinleyici

fx-sound kendi döngüsünü çalıştırmaz ve oyuncunun konumunu hiçbir zaman okumaz. Onu kullanan resource, dinleyici dönüşümünü kendisi göndermelidir: konum ile kameranın ileri vektörü. Bu olmadan her 3D ses dünyanın orijinine göre konumlanmış kalır.

lualocal function camForward()
    local rot = GetGameplayCamRot(2)
    local rx, rz = math.rad(rot.x), math.rad(rot.z)
    local cosRx = math.cos(rx)
    return vector3(-math.sin(rz) * cosRx, math.cos(rz) * cosRx, math.sin(rx))
end

CreateThread(function()
    while true do
        exports['fx-sound']:SetListener(GetEntityCoords(PlayerPedId()), camForward())
        Wait(60)
    end
end)
  • Döngüyü yalnızca 3D seslerinden biri varken çalıştır. Yalnızca 2D seslerin olduğu bir dünyanın dinleyiciye ihtiyacı yoktur.
  • Wait(60) yeterlidir. Motor, güncellemeler arasında dinleyicinin konumunu ve yönünü yumuşakça geçirir.

#Çalma export'ları

#Play

2D bir ses çalar: her yerde tam ses düzeyi, mesafeyle azalma yok.

lua---@param id string
---@param url string
---@param volume number  0.0 to 1.0
---@param loop boolean
---@param fadeIn? number  Milliseconds
exports['fx-sound']:Play(id, url, volume, loop, fadeIn)
luaexports['fx-sound']:Play('myui:click', 'https://example.com/click.mp3', 0.4, false)

fadeIn, çağrı anından değil, sesin gerçekten başladığı andan itibaren yükselir.

#PlayPos

Dünyaya sabitlenmiş ve dinleyiciye olan mesafeyle azalan bir 3D ses çalar.

lua---@param id string
---@param url string
---@param volume number  0.0 to 1.0
---@param coords vector3|table
---@param loop boolean
---@param distance number  Metres
---@param fadeIn? number  Milliseconds
exports['fx-sound']:PlayPos(id, url, volume, coords, loop, distance, fadeIn)
luaexports['fx-sound']:PlayPos('myjob:boombox', url, 0.8, GetEntityCoords(ped), true, 40)

Dinleyicinin güncellenmesi gerekir, yukarıya bak.

#Pause

Bir sesi duraklatır.

lua---@param id string
exports['fx-sound']:Pause(id)
luaexports['fx-sound']:Pause('myjob:boombox')

Kaynak hâlâ yüklenirken verilen duraklatma, kaynak hazır olduğunda uygulanır.

#Resume

Duraklatılmış bir sesi sürdürür.

lua---@param id string
exports['fx-sound']:Resume(id)
luaexports['fx-sound']:Resume('myjob:boombox')

#Stop

Bir sesi hemen durdurur ve kaldırır.

lua---@param id string
exports['fx-sound']:Stop(id)
luaexports['fx-sound']:Stop('myjob:boombox')

Id artık var olmaz: Exists false döndürür ve OnEnd tetiklenmez.

#FadeStop

Bir sesi sessizliğe kadar kısar, sonra kaldırır.

lua---@param id string
---@param ms number  Fade length in milliseconds
exports['fx-sound']:FadeStop(id, ms)
luaexports['fx-sound']:FadeStop('song:a', 800)
  • Lua kaydı hemen silinir: motor sesin sonunu çalarken GetPosition yanıt vermez ve OnEnd tetiklenmez.
  • Crossfade için iki farklı id kullan: eskisine FadeStop uygula, yenisini fadeIn ile PlayPos ile çal.

#Seek

Parçada bir konuma atlar.

lua---@param id string
---@param seconds number
exports['fx-sound']:Seek(id, seconds)
luaexports['fx-sound']:Seek('myjob:boombox', 42.5)

#Ses özelliği export'ları

Bunlar çalan bir sese uygulanır ve hemen etkili olur. Bilinmeyen bir id ile çağırmak hiçbir şey yapmaz.

#SetVolume

Bir sesin düzeyini değiştirir.

lua---@param id string
---@param volume number  0.0 to 1.0
---@param rampMs? number  How long the change takes, in milliseconds
exports['fx-sound']:SetVolume(id, volume, rampMs)
luaexports['fx-sound']:SetVolume('myjob:boombox', 0.35)

rampMs olmadan değişiklik, bir kaydırıcıya uygun kısa bir varsayılan geçiş kullanır. Dinleyicinin istemediği değişiklikler için, örneğin bir duvarın arkasına yürürken, birkaç yüz milisaniye ver.

#SetPosition

Bir 3D sesi taşır.

lua---@param id string
---@param coords vector3|table
exports['fx-sound']:SetPosition(id, coords)
luaexports['fx-sound']:SetPosition('myjob:boombox', GetEntityCoords(veh))

Yalnızca 3D sesler için. Motor, güncellemeler arasında yumuşak geçiş yapar.

#SetPositions

Tek bir sesi aynı anda birkaç noktaya sabitler; aynı sinyali çalan birkaç hoparlör kabini gibi.

lua---@param id string
---@param points table[]  List of vector3 or { x, y, z, heading? }
---@param distance? number  Metres
---@param cone? table  { inner, outer, outerGain } in degrees and linear gain
exports['fx-sound']:SetPositions(id, points, distance, cone)
luaexports['fx-sound']:SetPositions('club:main', { vector3(120.0, -1280.0, 29.0), vector3(128.0, -1280.0, 29.0) }, 40)
  • Tek nokta vermek SetPosition ile aynıdır.
  • Tablo olarak verilen bir nokta heading (oyun içi yön) taşıyabilir. Bu durumda kabin yönlüdür: önde tam düzey, arkada cone.outerGain.
  • Boş bir liste hiçbir şey yapmaz.

#SetDistance

Bir sesin en fazla duyulma mesafesini değiştirir.

lua---@param id string
---@param distance number  Metres
exports['fx-sound']:SetDistance(id, distance)
luaexports['fx-sound']:SetDistance('myjob:boombox', 60)

#SetEnvironment

Ses başına bir boğukluk ayarlar.

lua---@param id string
---@param env string  'none', 'car_closed', 'interior' or 'water'
exports['fx-sound']:SetEnvironment(id, env)
luaexports['fx-sound']:SetEnvironment('myjob:boombox', 'car_closed')

Sound.Env'deki kesim frekansıyla bir low-pass filtresi uygular.

#SetSpatial

Bir sesi yeniden yüklemeden 3D ile 2D arasında değiştirir.

lua---@param id string
---@param spatial boolean  true = 3D, false = 2D
---@param coords? vector3|table  One point, or a list of points; used when turning 3D on
---@param distance? number  Used when turning 3D on
exports['fx-sound']:SetSpatial(id, spatial, coords, distance)
luaexports['fx-sound']:SetSpatial('myjob:boombox', false)

Parça geçiş boyunca çalmaya devam eder. Dinleyici kaynağın tam üstündeyken işe yarar; örneğin hoparlörün bulunduğu arabanın içindeyken.

#SetFilters

Ses başına parametrik EQ ayarlar.

lua---@param id string
---@param bands? table[]  Ordered list of { type?, freq?, q?, gain? }; nil or {} removes the EQ
exports['fx-sound']:SetFilters(id, bands)
luaexports['fx-sound']:SetFilters('myjob:boombox', {
    { type = 'lowshelf', freq = 120.0, gain = 6.0 },
    { type = 'peaking', freq = 1000.0, gain = -3.0, q = 1.2 },
})
Alan Varsayılan Anlamı
type 'peaking' peaking, lowshelf, highshelf, lowpass, highpass, bandpass, notch, allpass
freq 1000.0 Hz cinsinden merkez ya da köşe frekansı. frequency da okunur
gain 0.0 dB cinsinden yükseltme ya da kesme. Yalnızca peaking ve iki shelf filtresi kullanır
q 1.0 Bant genişliği. Yüksek değer daha dardır. quality da okunur
  • Bantlar verilen sırayla zincirlenir.
  • Yalnızca değerler değiştiğinde (aynı bant sayısı, aynı türler) filtreler yeniden kullanılır ve parametreleri Sound.EqSmoothing boyunca yumuşakça geçer. Bant sayısını ya da bir türü değiştirmek zinciri yeniden kurar, bu yüzden bir hazır ayarı tek liste olarak gönder.
  • Çok noktalı bir sesin her noktasına tek bir zincir hizmet eder.
  • Sound.EqBandsMax, bir sesin taşıyabileceği bant sayısını sınırlar.

#Sorgu export'ları

Motorun her Sound.ProgressMs'de yenilediği yerel bir önbellekten yanıtlanır. Hiçbir zaman bekletmez (yield etmez).

#GetPosition

Çalma konumunu saniye cinsinden döndürür.

lua---@param id string
---@return number seconds  0 if unknown
exports['fx-sound']:GetPosition(id)
lualocal pos = exports['fx-sound']:GetPosition('myjob:boombox')

Değer gerçek çalmanın en fazla Sound.ProgressMs kadar gerisindedir.

#GetDuration

Parça uzunluğunu saniye cinsinden döndürür.

lua---@param id string
---@return number seconds  0 until metadata has loaded
exports['fx-sound']:GetDuration(id)
lualocal dur = exports['fx-sound']:GetDuration('myjob:boombox')

#Exists

Bu id ile bir sesin tutulup tutulmadığını söyler.

lua---@param id string
---@return boolean
exports['fx-sound']:Exists(id)
lualocal playing = exports['fx-sound']:Exists('myjob:boombox')

#GetAll

Çalan her sesin id'sini döndürür.

lua---@return string[] ids
exports['fx-sound']:GetAll()
luafor _, id in ipairs(exports['fx-sound']:GetAll()) do
    if id:sub(1, 6) == 'myjob:' then exports['fx-sound']:Stop(id) end
end

Sesler onları oluşturan resource'tan uzun yaşar. Resource'un durduğunda önekine uyan kendi id'lerini durdur. Liste diğer resource'ların seslerini de içerir.

#GetStats

Motorun son yük raporunu döndürür.

lua---@return table|nil stats  { sounds, ytAlive, ytBuilt, ytBuilt5m, audioBuilt, pageMin }
exports['fx-sound']:GetStats()
lualocal stats = exports['fx-sound']:GetStats()

İlk rapordan önce nil döndürür. NUI sayfası her yeniden yüklendiğinde sayılar sıfırlanır. Tanılama araçları içindir.

#Callback export'ları

Bunları Play ya da PlayPos'tan hemen sonra bağla; o çağrı döndüğünde kayıt zaten vardır. Id başına bir fonksiyon: yeniden bağlamak öncekinin yerini alır. Bilinmeyen bir id ile çağırmak hiçbir şey yapmaz.

#OnStart

Ses gerçekten başladığında çağrılan bir fonksiyon ayarlar.

lua---@param id string
---@param fn fun()
exports['fx-sound']:OnStart(id, fn)
luaexports['fx-sound']:OnStart(id, function() print('playing') end)

#OnEnd

Parça bittiğinde çağrılan bir fonksiyon ayarlar.

lua---@param id string
---@param fn fun()
exports['fx-sound']:OnEnd(id, fn)
luaexports['fx-sound']:OnEnd(id, function() playNextTrack() end)

OnEnd bir kaynak başarısız olduğunda da tetiklenir, böylece ona bağlı bir sıra çalışmayan bir URL'yi atlayıp devam eder. Fonksiyon argüman almaz.

#Dinleyici export'ları

Bunlar yerel oyuncunun duyduğu her şeyi etkiler. Bunları tek bir resource yönetmelidir.

#SetListener

Dinleyicinin konumunu ve yönünü ayarlar.

lua---@param coords vector3|table
---@param forward? vector3|table  Camera forward vector
exports['fx-sound']:SetListener(coords, forward)
luaexports['fx-sound']:SetListener(GetEntityCoords(PlayerPedId()), camForward())

3D ses için gereklidir.

#SetMasterEQ

Ana çıkıştaki bass boost hazır ayarını belirler.

lua---@param preset string  'off', 'low', 'medium' or 'high'
exports['fx-sound']:SetMasterEQ(preset)
luaexports['fx-sound']:SetMasterEQ('medium')

#SetListenerEnv

Dinleyici tarafında bir boğukluk ayarlar.

lua---@param env string  'none', 'car_closed', 'interior' or 'water'
exports['fx-sound']:SetListenerEnv(env)
luaexports['fx-sound']:SetListenerEnv(IsPedSwimmingUnderWater(PlayerPedId()) and 'water' or 'none')

#Server export'u

#GetVersionStatus

Güncelleme kontrolünün sonucunu döndürür.

lua---@return table status  { state: string, current: string, latest: string|nil, behind: number|nil }
exports['fx-sound']:GetVersionStatus()
lualocal status = exports['fx-sound']:GetVersionStatus()

state; uptodate, outdated, ahead, unknown, error veya disabled olur. Kontrol başlangıçtan birkaç saniye sonra çalışır, bu yüzden hemen ardından unknown görmeyi bekle. Sound.VersionCheck = false olduğunda disabled olur.

#YouTube URL'leri

Play ya da PlayPos'a normal bir YouTube bağlantısı ver. Client'ta YouTube'un kendi oynatıcısıyla çalar; ses aynı ses grafiğinden geçirildiği için konum, boğukluk ve bass her zamanki gibi uygulanır. Sunucunda hiçbir şey kurulmaz ya da çözümlenmez.

  • Yükleyicisi yerleştirmeyi kapatmış videolar çalamaz (yt_101 / yt_150 olarak bildirilir).
  • Sound.IdleRecycleMs ve Sound.YouTubeMax, bir client'ın kaç YouTube oynatıcısı tuttuğunu sınırlar.

#Sorun giderme

Sound.Debug = true ayarla, yeniden başlat ve F8 konsolunu izle. Sonra yeniden false yap.

Satır Anlamı
Süreye yakın bir zamanla END Parça sonuna kadar çaldı
time=0 started=false ile END Hiç ses üretmedi. Başarısız bir kaynak olarak değerlendir
ERROR code=2 Ağ hatası ya da engellenmiş istek
ERROR code=4 Kaynak desteklenmiyor; genellikle süresi dolmuş ya da IP'ye kilitli bir URL
ERROR code=yt_101 / yt_150 Yükleyici yerleştirmeye izin vermiyor
ERROR code=yt_api_unavailable YouTube'un oynatıcı script'i hiç yüklenmedi. Client bağlantısını kontrol et
STALL / RESUME Yayın buffer'ı boşaldı ve ne kadar süre boş kaldığı
  • Hiç ses yok: URL'nin https olduğunu ve ensure fx-sound'un onu kullanan resource'tan önce geldiğini doğrula.
  • 3D sesler hareket etmiyor: dinleyici SetListener ile güncellenmiyor.