کنترل دامنه با VolumeShaper

می‌توانید از VolumeShaper در یک برنامه صوتی برای اجرای محو کردن، محو کردن، محو کردن متقاطع، داک کردن و دیگر انتقال‌های خودکار کوتاه صدا استفاده کنید. کلاس VolumeShaper در اندروید 8.0 (سطح API 26) و بالاتر موجود است.

شما با فراخوانی createVolumeShaper() در یک نمونه از AudioTrack یا MediaPlayer یک VolumeShaper ایجاد می کنید. VolumeShaper فقط روی صدای تولید شده توسط AudioTrack یا MediaPlayer که آن را ایجاد کرده است عمل می کند.

VolumeShaper.Configuration

رفتار VolumeShaper با VolumeShaper.Configuration آن تعریف می شود. این پیکربندی یک *منحنی حجم، نوع interpolator و مدت زمان را مشخص می کند.

منحنی حجم

منحنی حجم نشان دهنده تغییر دامنه در طول زمان است. توسط یک جفت آرایه شناور، x[] و y[] که مجموعه ای از نقاط کنترل را تعریف می کنند، تعریف می شود. هر جفت (x, y) به ترتیب زمان و حجم را نشان می دهد. آرایه ها باید دارای طول مساوی بوده و دارای حداقل 2 و حداکثر 16 مقدار باشند. (حداکثر طول منحنی در getMaximumCurvePoints() تعریف شده است.)

مختصات زمانی در بازه [0.0، 1.0] داده می شود. اولین نقطه زمانی باید 0.0، آخرین آن باید 1.0 باشد و زمان ها باید به طور یکنواخت افزایش یابد.

مختصات حجم در مقیاس خطی در بازه [0.0، 1.0] مشخص می شود.

نوع درون یاب

منحنی حجم همیشه از نقاط کنترل مشخص شده عبور می کند. مقادیر بین نقاط کنترل با توجه به نوع درون یابی پیکربندی توسط یک spline به دست می آید. چهار ثابت برای انواع درون‌یابی VolumeShaper موجود است:

  • VolumeShaper.Configuration.INTERPOLATOR_TYPE_STEP
  • VolumeShaper.Configuration.INTERPOLATOR_TYPE_LINEAR
  • VolumeShaper.Configuration.INTERPOLATOR_TYPE_CUBIC
  • VolumeShaper.Configuration.INTERPOLATOR_TYPE_CUBIC_MONOTONIC

مدت زمان

مختصات زمانی مشخص شده در بازه [0.0، 1.0] به مدت زمانی که شما بر حسب میلی ثانیه تعیین می کنید، مقیاس می شوند. این طول واقعی منحنی حجم صدا را در زمانی که شکل دهنده در حال اجرا است و منحنی را روی خروجی صدا اعمال می کند، تعیین می کند.

با استفاده از VolumeShaper

ایجاد یک پیکربندی

قبل از ساختن یک VolumeShaper ، باید یک نمونه از VolumeShaper.Configuration ایجاد کنید. این کار را با استفاده از VolumeShaper.Configuration.Builder() انجام دهید:

کاتلین 

val config: VolumeShaper.Configuration = VolumeShaper.Configuration.Builder()
        .setDuration(3000)
        .setCurve(floatArrayOf(0f, 1f), floatArrayOf(0f, 1f))
        .setInterpolatorType(VolumeShaper.Configuration.INTERPOLATOR_TYPE_LINEAR)
        .build()

Java

VolumeShaper.Configuration config =
  new VolumeShaper.Configuration.Builder()
      .setDuration(3000)
      .setCurve(new float[] {0.f, 1.f}, new float[] {0.f, 1.f})
      .setInterpolatorType(VolumeShaper.Configuration.INTERPOLATOR_TYPE_LINEAR)
      .build();

With no arguments the VolumeShaper.Configuration.Builder constructor returns a builder that creates a configuration with default settings: INTERPOLATOR_TYPE_CUBIC, a one second duration, and no curve. You must add a curve to the builder before calling build().

The framework provides constants for configurations with pre-built curves, each with one second duration:

  • VolumeShaper.Configuration.LINEAR_RAMP
  • VolumeShaper.Configuration.CUBIC_RAMP
  • VolumeShaper.Configuration.SINE_RAMP
  • VolumeShaper.Configuration.SCURVE_RAMP

Creating a VolumeShaper

To create a VolumeShaper, call createVolumeShaper() on an instance of the appropriate class, passing in a VolumeShaper.Configuration:

Kotlin

volumeShaper = myMediaPlayer.createVolumeShaper(config)
volumeShaper = myAudioTrack.createVolumeShaper(config)

Java

volumeShaper = myMediaPlayer.createVolumeShaper(config);
volumeShaper = myAudioTrack.createVolumeShaper(config);

A single track or media player can have many shapers attached to it, and you can control each shaper separately. The outputs of all the shapers on a track or player are multiplied together. A VolumeShaper cannot be shared between AudioTracks or MediaPlayers, but you can use the same configuration in calls to createVolumeShaper to build identical shapers on multiple AudioTracks or MediaPlayers.

When you create the shaper, its first control point (at t = 0) is applied to the audio stream. If the initial volume is not 1.0 and your app is playing material at create time, your audio might have an abrupt change in volume. Best practice is to start playing audio from silence and use a VolumeShaper to implement a fade-in when playback starts. Create a VolumeShaper that starts at 0 volume and fades up. For example:

setCurve(new float[] {0.f, 1.f}, new float[] {0.f, 1.f})

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

اجرای VolumeShaper

اگرچه سطح صدا اولین نقطه کنترلی به محض ایجاد شکل دهنده به مسیر صوتی اعمال می شود، شکل دهنده در طول منحنی پیشرفت نمی کند تا زمانی که متد apply() را با VolumeShaper.Operation.PLAY فراخوانی کنید. پس از ایجاد شکل‌دهنده، اولین فراخوانی apply() باید عملیات PLAY برای شروع شکل‌دهنده مشخص کند. این منحنی را از اولین تا آخرین نقاط کنترل اجرا می کند:

کاتلین

shaper.apply(VolumeShaper.Operation.PLAY)

Java

shaper.apply(VolumeShaper.Operation.PLAY);

هنگامی که شکل دهنده در حال اجرا است، می توانید فراخوانی های متناوب apply() را صادر کنید که عملیات REVERSE و PLAY را مشخص می کند. این امر هر بار جهت بازخوانی نقاط کنترل را تغییر می دهد.

شکل دهنده به طور مداوم صدا را تنظیم می کند و از تمام نقاط کنترل عبور می کند تا زمانی که منقضی شود . این زمانی اتفاق می افتد که شکل دهنده به آخرین (برای عملیات PLAY) یا اولین (برای عملکرد REVERSE) نقطه کنترل در منحنی برسد.

هنگامی که شکل دهنده منقضی می شود، صدا در آخرین تنظیم باقی می ماند که ممکن است اولین یا آخرین نقطه کنترل باشد. می‌توانید در هر زمان VolumeShaper.getVolume() را برای سطح حجم فعلی فراخوانی کنید.

پس از انقضای شکل‌دهنده، می‌توانید apply() aply را برای اجرای منحنی در جهت مخالف صادر کنید. به عنوان مثال، اگر شکل دهنده در حین اجرای PLAY منقضی شده باشد، apply() بعدی باید REVERSE باشد. فراخوانی PLAY پس از انقضای PLAY ، یا REVERSE پس از انقضای REVERSE هیچ تاثیری ندارد.

باید عملیات PLAY و REVERSE را جایگزین کنید. هیچ راهی برای پخش یک منحنی از اولین تا آخرین نقطه کنترل و سپس راه اندازی مجدد آن از اولین نقطه کنترل وجود ندارد. برای جایگزینی منحنی با یک کپی از خودش، می‌توانید از متد replace() که در بخش بعدی توضیح داده شد استفاده کنید. این شکل‌دهنده را بازنشانی می‌کند و برای شروع دوباره به عملیات PLAY نیاز دارد.

تغییر منحنی

از متد replace() برای تغییر منحنی VolumeShaper استفاده کنید. این روش یک پیکربندی، یک عملیات و یک پارامتر اتصال را می گیرد. شما می توانید متد replace() در هر زمانی که شکل دهنده در حال اجرا است یا پس از انقضای آن فراخوانی کنید:

کاتلین

val newConfig = VolumeShaper.Configuration.Builder()
        .setDuration(1000)
        .setCurve(floatArrayOf(0f, 0.5f), floatArrayOf(0f, 1f))
        .setInterpolatorType(VolumeShaper.Configuration.INTERPOLATOR_TYPE_LINEAR)
        .build()
val join = true
shaper.replace(newConfig, VolumeShaper.Operation.PLAY, join)

Java

VolumeShaper.Configuration newConfig =
  new VolumeShaper.Configuration.Builder()
    .setDuration(1000)
    .setCurve(new float[] {0.f, 0.5f}, new float[] {0.f, 1.f})
    .setInterpolatorType(VolumeShaper.Configuration.INTERPOLATOR_TYPE_LINEAR)
    .build();
boolean join = true;
shaper.replace(newConfig, VolumeShaper.Operation.PLAY, join);

هنگامی که در حالی که شکل دهنده در حال اجرا است، replace() می خوانید، تغییر صدا را متوقف می کند و در مقدار فعلی خود باقی می ماند. سپس شکل دهنده سعی می کند منحنی جدید را از اولین نقطه کنترل شروع کند. این بدان معنی است که آرگومان عملیات کنترل می کند که شکل دهنده پس از فراخوانی اجرا شود یا خیر. PLAY برای شروع فوری منحنی جدید مشخص کنید، REVERSE را مشخص کنید تا شکل دهنده در حجم اولین نقطه کنترل در منحنی جدید متوقف شود. می توانید شکل دهنده را بعداً با apply(VolumeShaper.Operation.PLAY) شروع کنید.

هنگامی که replace() با join = false فراخوانی می کنید، شکل دهنده منحنی خود را در سطح مشخص شده توسط اولین نقطه کنترل خود شروع می کند. این می تواند باعث ناپیوستگی در صدا شود. می توانید با فراخوانی replace() با join = true از این امر جلوگیری کنید. این اولین نقطه کنترل منحنی جدید را روی سطح فعلی شکل دهنده تنظیم می کند و حجم تمام نقاط کنترل بین اولین و آخرین را برای حفظ شکل نسبی منحنی جدید مقیاس می کند (آخرین نقطه کنترل بدون تغییر است). عملیات مقیاس بندی نقاط کنترل را در منحنی جدید شکل دهنده به طور دائم تغییر می دهد.

حذف VolumeShaper

هنگامی که AudioTrack یا MediaPlayer منتشر می شود یا دیگر استفاده نمی شود، سیستم بسته می شود و زباله ها VolumeShaper را جمع آوری می کنند. می توانید متد close() روی شکل دهنده فراخوانی کنید تا بلافاصله آن را از بین ببرید. این سیستم شکل دهنده را از خط لوله صدا در حدود 20 میلی ثانیه حذف می کند. هنگام پخش صدا هنگام بستن VolumeShaper مراقب باشید. اگر هنگام فراخوانی close() ولوم شکل دهنده کمتر از 1.0 باشد، مقیاس حجم شکل دهنده به 1.0 تغییر می کند. این می تواند باعث افزایش ناگهانی حجم شود.