Ö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.luaiçindekiConfig.Sound.Resourceses altyapısını seçer:auto,fx-sound,xsoundveyanone.autoolduğunda, başlatılmışsafx-soundkullanılır.Config.Sound.Enable3D,RangeveBystanderVolume, 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
PlayPosile çalınır,SetPositionile taşınır,SetVolumeile kısılır veStopile 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
GetPositionyanıt vermez veOnEndtetiklenmez. - Crossfade için iki farklı id kullan: eskisine
FadeStopuygula, yenisinifadeInilePlayPosile ç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
SetPositionile 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, arkadacone.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.EqSmoothingboyunca 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_150olarak bildirilir). Sound.IdleRecycleMsveSound.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
SetListenerile güncellenmiyor.