🎵 akuibots-musical (Python)

Plugin musik untuk bot — bukan bot-nya. Kirim judul atau link (YouTube / Spotify), plugin balas metadata lengkap: thumbnail, judul, durasi, pembuat — plus audio stream yang siap diputar di voice bot.

🟢 Versi Node.js: akuibots-musical di npm — API-nya sengaja dibuat mirip, tinggal pindah bahasa.

from akuibots_musical import Musical

music = Musical()

track = music.play("a!p alan walker faded")   # judul → dicari otomatis di YouTube
track = music.play("https://youtu.be/60ItHLz5WEA")                          # link YouTube
track = music.play("https://open.spotify.com/track/4uLU6hMCjMI75M1A2tKUQC") # link Spotify

print(track.title)          # Alan Walker - Faded
print(track.author)         # Alan Walker
print(track.duration_text)  # 3:33
print(track.thumbnail)      # https://i.ytimg.com/vi/.../hqdefault.jpg

handle = music.get_stream(track)
print(handle.url)           # URL audio → pipa ke ffmpeg (voice bot)

✨ Fitur

• 🔎 Kirim judul → dicari otomatis di YouTube (kayak ytsearch), ambil hasil teratas
• 🔗 Kirim link → YouTube (watch / youtu.be / shorts / live / music) & Spotify (track / album / playlist / artist) langsung dikenali
• 🖼️ Data lengkap: thumbnail, judul, durasi, pembuat (uploader), views, status live
• 🔊 Audio stream siap dipipa ke ffmpeg — discord.py, py-cord, Telegram, CLI, apa saja
• ⚡ Tanpa Lavalink, tanpa API key, tanpa browser headless
• 🧹 Pembersih perintah otomatis: a!p faded, !play faded, music-bot!p faded → faded
• 🌐 Spotify tanpa API key (token anonim embed + fallback oEmbed) → dicocokkan ke YouTube untuk audionya
• 🐍 Dependency minimal: yt-dlp + requests — Python ≥ 3.8
• 🌀 Async ready: play_async() dkk. untuk bot berbasis asyncio (discord.py, dll)

📦 Instalasi

pip install akuibots-musical

Untuk memutar audio di voice bot kamu juga butuh ffmpeg terpasang di server (apt install ffmpeg / brew install ffmpeg).

🚀 Quick Start

1 — Instal:

pip install akuibots-musical

2 — Play dari judul (alur a!p):

from akuibots_musical import Musical

music = Musical()
track = music.play("a!p alan walker faded")
# prefix 'a!p' otomatis dibuang → dicari 'alan walker faded' di YouTube

3 — Play dari link (YouTube / Spotify):

track = music.play("https://www.youtube.com/watch?v=60ItHLz5WEA")
track = music.play("https://open.spotify.com/track/4uLU6hMCjMI75M1A2tKUQC")
# Spotify → metadata diambil tanpa API key, lalu dicocokkan ke YouTube

4 — Ambil audio untuk voice:

handle = music.get_stream(track)      # atau music.get_stream("a!p faded")
print(handle.url)                     # URL audio langsung (m4a/opus)

📦 Isi Track

🔊 Isi StreamHandle

URL audio berlaku ± 6 jam dan terikat IP — ambil ulang (get_stream) setiap kali memutar, jangan simpan lama.

🔎 Cara kerja — alur a!p

User : a!p faded
  └─> bot memanggil music.play("a!p faded")
        └─> buang prefix 'a!p'   → 'faded'
        └─> bukan link           → cari di YouTube (ytsearch)
        └─> ambil hasil teratas  → Track {title, author, duration, thumbnail, url}
  └─> bot balas embed (thumbnail + judul + durasi + channel)
  └─> music.get_stream(track) → URL audio → ffmpeg → voice channel

Link dikenali otomatis: YouTube → ambil langsung; Spotify → ambil metadata lalu cocokkan ke YouTube; link lain → error UNSUPPORTED_SOURCE.

📖 API Reference

Musical(strip_prefix=True, default_limit=5, ytdlp_options=None)

Metode

Fungsi standalone (instance default)

from akuibots_musical import play, resolve, search, get_stream, play_stream
track = play("a!p faded")

Helper

parse_command, strip_command_prefix, is_url, detect_source, format_duration, extract_youtube_id, resolve_spotify — dan MusicalError dengan .code: INVALID_INPUT, NOT_FOUND, SEARCH_FAILED, UNSUPPORTED_SOURCE, SPOTIFY_FAILED, STREAM_FAILED.

🤖 Contoh: Bot Discord (discord.py)

import discord
from discord.ext import commands
from akuibots_musical import Musical

music = Musical()
intents = discord.Intents.default()
intents.message_content = True
bot = commands.Bot(command_prefix="a!", intents=intents)

@bot.event
async def on_ready():
    print("Bot siap:", bot.user)

@bot.command()
async def p(ctx, *, query: str):
    """a!p <judul/link> → play musik di voice channel."""
    if not ctx.author.voice:
        return await ctx.send("Masuk voice channel dulu ya 🎧")
    await ctx.send(f"🔍 Mencari: `{query}`")

    track = await music.play_async(query)          # judul ATAU link
    handle = await music.get_stream_async(track)   # metadata + audio

    if ctx.voice_client is None:
        await ctx.author.voice.channel.connect()

    # ✅ Pola paling awet (2025+): yt-dlp yang mengunduh audionya
    # (headers & PO token diurus yt-dlp), lalu dipipa ke ffmpeg.
    # URL mentah handle.url langsung ke ffmpeg sering DITOLAK YouTube
    # (bot jalan tapi tanpa suara).
    ytdlp_proc, ff_proc = handle.pcm_popen()
    source = discord.PCMAudio(ff_proc.stdout)

    def selesai(e):
        for p in (ytdlp_proc, ff_proc):
            try:
                p.kill()
            except Exception:
                pass
        if e:
            print("FFmpeg error:", e)

    ctx.voice_client.stop()
    ctx.voice_client.play(source, after=selesai)

    embed = discord.Embed(title=track.title, url=track.url, color=0x2B6CB0)
    embed.set_thumbnail(url=track.thumbnail)
    embed.add_field(name="Durasi", value=track.duration_text, inline=True)
    embed.add_field(name="Channel", value=track.author, inline=True)
    embed.set_footer(text=f"Sumber: {track.source}")
    await ctx.send(embed=embed)

bot.run("TOKEN_BOT")

✈️ Contoh: Bot Telegram (python-telegram-bot)

from telegram.ext import Application, CommandHandler, ContextTypes
from telegram import Update
from akuibots_musical import Musical

music = Musical()

async def p(update: Update, context: ContextTypes.DEFAULT_TYPE):
    query = " ".join(context.args or [])
    if not query:
        return await update.message.reply_text("Kirim judul atau link: /p faded")
    msg = await update.message.reply_text(f"🔍 Mencari: {query}")
    track, handle = await music.play_stream_async(query)
    await msg.edit_text(
        f"🎵 {track.title}\n"
        f"👤 {track.author}\n"
        f"⏱ {track.duration_text}\n"
        f"🔗 {track.url}"
    )
    # opsional — kirim file audionya juga:
    # handle.save("lagu.m4a") lalu reply_audio

app = Application.builder().token("TOKEN_BOT").build()
app.add_handler(CommandHandler("p", p))
app.run_polling()

🖥️ Contoh: CLI

#!/usr/bin/env python3
import subprocess, sys
from akuibots_musical import music

track, handle = music.play_stream(" ".join(sys.argv[1:]))
print(f"▶ {track.title} — {track.author}  [{track.duration_text}]")
subprocess.run(["ffplay", "-nodisp", "-autoexit", "-loglevel", "quiet", handle.url])

python player.py "a!p alan walker faded"

⚙️ Opsi yt-dlp & cookies

Semua opsi yt-dlp bisa diteruskan lewat ytdlp_options:

music = Musical(ytdlp_options={
    "cookiefile": "cookies.txt",                       # cookies browser (Netscape)
    "extractor_args": {"youtube": {"player_client": ["ios", "web"]}},
})

🆘 Troubleshooting

❓ FAQ

Ini bot Discord? Bukan. Ini plugin/library yang dipasang di bot kamu (Discord, Telegram, WhatsApp, CLI, apa saja). Bot yang memproses perintah a!p, plugin ini yang mengerjakan musiknya.

Sama kayak Lavalink? Gak perlu server Lavalink, gak perlu Java, gak perlu API key. Cukup pip install akuibots-musical — pencarian & stream langsung jalan.

Kenapa Spotify cuma dapat metadata? Spotify tidak menyediakan audio untuk pihak ketiga. Plugin mengambil metadata Spotify (judul + artis), lalu otomatis mencocokkannya ke YouTube — jadi music.play_stream(<link spotify>) tetap menghasilkan audio.

Bisa buat download mp3? Bisa — handle.save("lagu.m4a"), atau konversi pakai ffmpeg ke mp3.

Bedanya dengan versi npm?

Pakai yt-dlp? Ya — mesin pencarian & ekstraksi memakai yt-dlp yang aktif dirawat, jadi jauh lebih tahan perubahan YouTube daripada library ytdl-core lama.

📄 Lisensi

MIT — © 2026 Akuibots. Versi npm: akuibots-musical.