Mengontrol amplitudo dengan VolumeShaper

Anda dapat menggunakan VolumeShaper di aplikasi audio untuk melakukan fade-in, fade-out, cross fade, ducking, dan transisi volume otomatis singkat lainnya. Class VolumeShaper tersedia di Android 8.0 (level API 26) dan yang lebih baru.

Anda membuat VolumeShaper dengan memanggil createVolumeShaper() pada instance AudioTrack atau MediaPlayer. VolumeShaper hanya bertindak pada audio yang dihasilkan oleh AudioTrack atau MediaPlayer yang membuatnya.

VolumeShaper.Configuration

Perilaku VolumeShaper ditentukan oleh VolumeShaper.Configuration-nya. Konfigurasi menentukan *kurva volume, jenis interpolator, dan durasi.*

Kurva volume

Kurva volume merepresentasikan perubahan amplitudo dari waktu ke waktu. Kurva ini ditentukan oleh sepasang array float, x[] dan y[] yang menentukan serangkaian titik kontrol. Setiap pasangan (x, y) masing-masing mewakili waktu dan volume. Array harus memiliki panjang yang sama dan berisi minimal 2 dan maksimal 16 nilai. (Panjang kurva maksimum ditentukan dalam getMaximumCurvePoints().)

Koordinat waktu ditentukan pada interval [0,0, 1,0]. Titik waktu pertama harus 0,0, titik waktu terakhir harus 1,0, dan waktunya harus meningkat secara monoton.

Koordinat volume ditentukan dalam skala linear selama interval [0,0, 1,0].

Jenis interpolator

Kurva volume selalu melewati titik kontrol yang ditentukan. Nilai di antara titik kontrol diperoleh oleh spline sesuai dengan jenis interpolator konfigurasi. Ada empat konstanta untuk jenis interpolator VolumeShaper yang tersedia:

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

Durasi

Koordinat waktu yang ditentukan dalam interval [0.0, 1.0] diskalakan ke durasi yang Anda tentukan dalam milidetik. Hal ini menentukan durasi sebenarnya dari kurva volume saat pembentuk berjalan dan menerapkan kurva ke output audio.

Menggunakan VolumeShaper

Membuat konfigurasi

Sebelum membuat VolumeShaper, Anda harus membuat instance VolumeShaper.Configuration. Lakukan hal ini menggunakan 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()

Tanpa argumen, konstruktor VolumeShaper.Configuration.Builder menampilkan builder yang membuat konfigurasi dengan setelan default: INTERPOLATOR_TYPE_CUBIC, durasi satu detik, dan tanpa kurva. Anda harus menambahkan kurva ke builder sebelum memanggil build().

Framework ini menyediakan konstanta untuk konfigurasi dengan kurva bawaan, masing-masing dengan durasi satu detik:

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

Membuat VolumeShaper

Untuk membuat VolumeShaper, panggil createVolumeShaper() pada instance class yang sesuai, dengan meneruskan VolumeShaper.Configuration:

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

Satu trek atau pemutar media dapat memiliki banyak pembentuk yang terpasang, dan Anda dapat mengontrol setiap pembentuk secara terpisah. Output dari semua pembentuk pada trek atau pemain dikalikan bersama. VolumeShaper tidak dapat dibagikan antara AudioTracks atau MediaPlayers, tetapi Anda dapat menggunakan konfigurasi yang sama dalam panggilan ke createVolumeShaper untuk membangun shaper yang identik di beberapa AudioTracks atau MediaPlayers.

Saat Anda membuat shaper, titik kontrol pertamanya (pada t = 0) diterapkan ke aliran audio. Jika volume awal bukan 1.0 dan aplikasi Anda memutar materi pada waktu pembuatan, audio Anda mungkin mengalami perubahan volume yang tiba-tiba. Praktik terbaiknya adalah mulai memutar audio dari senyap dan menggunakan VolumeShaper untuk menerapkan fade-in saat pemutaran dimulai. Buat VolumeShaper yang dimulai dengan volume 0 dan meningkat secara bertahap. Contoh:

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

Mulai pemutaran dan shaper secara bersamaan. Hal ini memastikan bahwa pemutaran dimulai dari senyap dan volume meningkat hingga volume penuh. Hal ini dijelaskan di bagian berikutnya.

Menjalankan VolumeShaper

Meskipun tingkat volume titik kontrol pertama diterapkan ke jalur audio segera setelah pembentuk dibuat, pembentuk tidak akan bergerak di sepanjang kurva hingga Anda memanggil metode apply() dengan VolumeShaper.Operation.PLAY. Setelah membuat shaper, pemanggilan pertama apply() harus menentukan operasi PLAY untuk memulai shaper. Tindakan ini akan menjalankan kurva dari titik kontrol pertama hingga terakhir:

shaper.apply(VolumeShaper.Operation.PLAY)

Saat shaper berjalan, Anda dapat mengeluarkan panggilan apply() bergantian yang menentukan operasi REVERSE dan PLAY. Tindakan ini akan mengubah arah pembacaan titik kontrol setiap saat.

Shaper terus menyesuaikan volume dan melewati semua titik kontrol hingga berakhir. Hal ini terjadi saat pembentuk mencapai titik kontrol terakhir (untuk operasi PLAY) atau pertama (untuk operasi REVERSE) dalam kurva.

Saat pembentuk berakhir, volume tetap berada di setelan terakhir, yang mungkin merupakan titik kontrol pertama atau terakhir. Anda dapat memanggil VolumeShaper.getVolume() untuk level volume saat ini kapan saja.

Setelah shaper berakhir, Anda dapat mengeluarkan panggilan apply() lain untuk menjalankan kurva ke arah yang berlawanan. Misalnya, jika shaper berakhir saat menjalankan PLAY, apply() berikutnya harus REVERSE. Memanggil PLAY setelah masa berlaku PLAY berakhir, atau REVERSE setelah masa berlaku REVERSE berakhir tidak akan berpengaruh.

Anda harus menjalankan operasi PLAY dan REVERSE secara bergantian. Tidak ada cara untuk memutar kurva dari titik kontrol pertama hingga terakhir, lalu memulai ulang lagi dari titik kontrol pertama. Anda dapat menggunakan metode replace(), yang dijelaskan di bagian berikutnya, untuk mengganti kurva dengan salinannya sendiri. Tindakan ini akan mereset pembentuk, sehingga memerlukan operasi PLAY untuk memulainya lagi.

Mengubah kurva

Gunakan metode replace() untuk mengubah kurva VolumeShaper. Metode ini menggunakan konfigurasi, operasi, dan parameter join. Anda dapat memanggil metode replace() kapan saja, saat pembentuk sedang berjalan atau setelah masa berlakunya berakhir:

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)

Saat Anda memanggil replace() saat pembentuk sedang berjalan, pembentuk akan berhenti mengubah volume dan tetap pada nilainya saat ini. Kemudian, pembentuk mencoba memulai kurva baru dari titik kontrol pertama. Artinya, argumen operasi mengontrol apakah shaper berjalan setelah panggilan atau tidak. Tentukan PLAY untuk segera memulai kurva baru, tentukan REVERSE untuk membiarkan pembentuk dijeda pada volume titik kontrol pertama dalam kurva baru. Anda dapat memulai shaper nanti dengan apply(VolumeShaper.Operation.PLAY).

Saat Anda memanggil replace() dengan join = false, pembentuk memulai kurvanya pada tingkat yang ditentukan oleh titik kontrol pertamanya. Hal ini dapat menyebabkan diskontinuitas dalam volume. Anda dapat menghindarinya dengan memanggil replace() dengan join = true. Tindakan ini akan menetapkan titik kontrol pertama kurva baru ke level pembentuk saat ini dan menskalakan volume semua titik kontrol antara titik pertama dan terakhir untuk mempertahankan bentuk relatif kurva baru (titik kontrol terakhir tidak berubah). Operasi penskalaan akan mengubah titik kontrol secara permanen dalam kurva baru pembentuk.

Menghapus VolumeShaper

Sistem akan menutup dan melakukan pembersihan sampah memori pada VolumeShaper saat AudioTrack atau MediaPlayer-nya dirilis atau tidak lagi digunakan. Anda dapat memanggil metode close() pada pembentuk untuk segera menghancurkannya. Sistem akan menghapus pembentuk dari pipeline audio dalam waktu sekitar 20 md. Berhati-hatilah saat menutup VolumeShaper saat audio diputar. Jika pembentuk memiliki volume kurang dari 1,0 saat Anda memanggil close(), skala volume pembentuk akan berubah menjadi 1,0. Hal ini dapat menyebabkan peningkatan volume secara tiba-tiba.