yutify

✨ TABLE OF CONTENTS

• yutify ← you're here..
  • Features ™️
  • Available Music Platforms 📻
  • Running yutify 🧑‍💻
    • Environment Variables 🔐
  • Contributing 🤝
  • Disclaimer ⚠️
  • Acknowledgement // End Note 🙃

✨ SCREENSHOTS

OwO

yutify is a simple RESTful API and full-stack web application for retrieving music info, streaming links, and user activity from various platforms. It also provides beautiful, ready-to-embed music and activity cards for your website or blog. To prevent abuse, the API enforces a rate limit of 20 requests per minute per user.

Right now, it only retrieves streaming links for these music platforms. If you'd like to suggest additional platforms or metadata, feel free to open an issue. You can visit the website to explore here and make sure to read the docs as well.

💜 Support yutify: yutify is free and open-source! If you find it useful, you can always support development on ko-fi or by starring the repo. Thank you!

Features ™️

• 🎵 Multi-Platform Music Search: Retrieve streaming links and detailed metadata for songs from Apple Music, Deezer, KKBox, Spotify, and YouTube Music.
• 🧑‍💻 RESTful & Developer-Friendly: Clean, well-documented API with rate limiting, error handling, and easy integration for any app or website.
• 🔍 Flexible Search API: Search by artist and song name, or request information from a specific platform using a simple query parameter (e.g., ?spotify).
• 🖼️ Embeddable Music Info & Activity Cards: Instantly get a ready-to-embed HTML music card for any song using the ?embed query parameter—perfect for blogs, websites, or sharing. You can also embed your current or recent listening activity (from Spotify or Last.fm) on your own site, or share it with others. Public profiles let you share your listening activity with anyone; private profiles (default) keep your activity visible only to you.
• 📝 Lyrics Support: Fetch lyrics for many tracks (where available).
• 🔒 OAuth 2.0 & Account Features: Secure user authentication, service linking, and privacy controls. Supports 2FA and account management. Developer Dashboard for creating and managing apps for 2FA and OAuth 2.0 authentication.
• 🚀 Fast, Modern, and Open Source: Powered by Flask (Python), yutipy, and Pico CSS. Free to use, easy to deploy, and open for contributions!
• 🌐 Self-Contained Embeds: Embeds are fully self-contained (HTML+CSS without any JavaScript), require no external dependencies, and are safe to use in any site or CMS.

Available Music Platforms 📻

Alphabetically sorted

• Apple Music
• Deezer
• KKBox
• Last.fm
• Spotify
• YouTube Music

Running yutify 🧑‍💻

1. Clone the repository:

git clone https://github.com/CheapNightbot/yutify.git

2. Install dependencies:

pip install -r requirements.txt

Before running yutify, you need to take care of a few things:

Environment Variables 🔐

For certain configurations, it relies on environment variables that must be set before running yutify. Here's a brief overview:

Tip

There is a .env_example file in the root directory of the project. Rename it to .env and replace placeholder values with actual values when running the project locally. When using a hosting provider, set the respective values in the environment variable settings provided by them.

Required: These environment variables are mandatory!

• SECRET_KEY: Used by Flask for session management and security. To generate a secure key, you may run the following command:

  python -c "import secrets; print(secrets.token_hex())"

• ENCRYPTION_KEY: A URL-safe base64-encoded 32-byte key used for encrypting access token information (for the services that require authorization like Spotify & KKBox for searching music) and to encrypt the (2FA) recovery codes at rest (i.e. in the database). To generate an encryption key, run the following command after installing dependencies:

  python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

  • Important: Once used to encrypt, changing or losing this key will prevent decryption of previously encrypted data. Handle with care!

• SECURITY_PASSWORD_SALT: Specifies the HMAC salt. This is used for double hashing the password. A good salt can be generated using the following command:

  python -c "import secrets; print(secrets.SystemRandom().getrandbits(128))"

• SECURITY_TOTP_SECRETS: Secret used to encrypt the totp_password both into DB and into the session cookie. You should run the following command to generate one after installing dependencies:

  python  -c "from passlib import totp; print(totp.generate_secret());"

Optional: These environment variables are optional!

• SERVICE: The service / application name. Default to "yutify". You may set it to anything you want. It will be used / shown in various places like, home/index page, meta tags, email, etc.
• SERVICE_EMAIL: An email address which will be used in privacy policy and terms of service pages at the bottom (after obfuscating).
• HOST_URL: The URL where the application itself is currently running. It will be used in meta tags and just used for sending logging emails (error and above) to the admin email. The default is localhost, so the email "from" field will look like this: From: <no-reply@localhost>
• PORT: The port number on which the application will serve HTTP requests. Defaults to 5000.
• LOG_TO_STDOUT: Whether to use file based logging or log to the console. Set this variable to 1 to enable console logging and 0 or omit it to use file based logging.
• DATABASE_URL: SQL Database URL. If not set, a file-based SQLite database (app.db) will be used in the root directory.
• YUTIFY_MAIL_ERROR_LOGS: If set to 1, logs for error and above level will be sent to the email set in the ADMIN_EMAIL variable. To disable sending logs to email, set it to 0 or simply omit it.
• YUTIFY_ACCOUNT_DELETE_EMAIL: Whether to send account deletion confirmation email to the user when they decide to delete their account. Set this to 0 to disable it. Default to 1 (will send email).
• SECURITY_REGISTERABLE: Whether to allow user registration / sign up or not. Set this variable to 1 to enable user sign up and 0 or omit it to disable user sign up.
• SECURITY_CONFIRMABLE: Whether users are required to confirm their email address when registering a new account. If set to 1 (default), a confirmation email will sent to the user's email and they can't login without confirming their account. Set it to 0 to disable it.
• RETURN_GENERIC_RESPONSES: Whether to return generic responses for auth endpoints. Set it to 0 to disable it. Default to enabled (i.e. 1).
• CHECK_EMAIL_DELIVERABILITY: When user signup, check if email address exists (or is fake) and whether emails can be sent to that address. Set it to 1 to enable it or 0 to disable it. By default it is enabled.
• For retrieving music information from Spotify, KKBox, and Last.fm, client IDs, client secrets, or API keys are required. Thankfully, yutipy provides a command-line utility to obtain these values. Run yutipy-config in your terminal after installing dependencies. The wizard will guide you through obtaining and setting up API keys for supported services like KKBOX, Last.fm, and Spotify. These values are automatically saved in the .env file.
  • KKBOX_CLIENT_ID, KKBOX_CLIENT_SECRET, SPOTIFY_CLIENT_ID, SPOTIFY_CLIENT_SECRET, SPOTIFY_REDIRECT_URI, LASTFM_API_KEY
  • Without these variables, interaction with these platforms will be unavailable.
• Variables for sending emails (used for error logs and password resets):
  • MAIL_SERVER: The mail server address (e.g., smtp.gmail.com).
  • MAIL_PORT: The port to use for the mail server (e.g., 587 for TLS).
  • MAIL_USE_TLS: Whether to use TLS for secure email communication. Set this variable to 1 to enable TLS and 0 or omit it to disable TLS.
  • MAIL_USERNAME: The email address to use for sending emails.
  • MAIL_PASSWORD: The password or app-specific password for the email account.
  • ADMIN_EMAIL: The administrator's email address to receive error logs or notifications. It will also be used to create a defult admin user when first running yutify (see below "Run the application"!).
• RATELIMIT: Enables rate-limiting on all API routes (/api/*). For valid values, refer to the Flask-Limiter Docs.
• REDIS_URI: URI for Redis (used for rate-limiting and caching). If not set:
  • With FLASK_DEBUG=1 (development mode), in-memory caching will be used.
  • Without FLASK_DEBUG (production mode), caching will be disabled.
• ENABLE_CAPTCHA: Whether to enable captcha on login and signup forms or not. Set this to 1 to enable captcha and 0 or omit it to disable captcha.
• For captcha, yutify uses Flask-WTF. Which comes with default configs for reCaptcha. However, if you want to use different captcha (e.g. hCaptcha), you may set these variables in environment variable (or .env file):
  • CUSTOM_CAPTCHA: Set to 1 if using different captcha than the Flask-WTF comes with and 0 or omit it to use default configs. (ENABLE_CAPTCHA should also be set to 1 otherwise this variable will be ignored and no captcha will be enabled).
  • Following variables define the configs for custom captcha. Please consult the Flask-WTF Docs. CUSTOM_CAPTCHA must be set to 1 else, these will be ignored:
  • RECAPTCHA_PUBLIC_KEY, RECAPTCHA_PRIVATE_KEY, RECAPTCHA_SCRIPT, RECAPTCHA_DIV_CLASS, RECAPTCHA_VERIFY_SERVER

3. Run the application:

Important

Make sure you are at the root of the project directory before running commands below!

Visit the application locally at: http://localhost:<PORT> or http://127.0.0.1:<PORT> ~ Replace the <PORT> with the port number you defined in environment variable (or .env file) Or the default 5000.

When using a hosting provider, use the link provided by them for your deployed project.

flask db upgrade

python yutify.py

Warning

Regardless of the user registration / signup is enabled or disabled, a default admin user with the email set in the ADMIN_EMAIL environment variable will be created when you will run the project. It will be created only if a user with that email does not exist in the database. You must change the username and password for it after logging in as this user. Please check the default values below:

• name: "Admin"
• username: "admin"
• email: value set in ADMIN_EMAIL environment variable
• password: "senpai-likes-small-potatoes"

Contributing 🤝

We welcome contributions from everyone! Here's how you can help:

• Open Issues: If you have suggestions, improvements, or bug reports, feel free to open an issue.
• Fork and Develop: Fork the repository, create a new branch for your changes, and make modifications in that branch.
• Submit Pull Requests: Once your changes are ready, open a pull request for review.

Whether you're a user or a developer, your contributions are valuable and appreciated!

Disclaimer ⚠️

All trademarks, logos, and content displayed in this project are the property of their respective owners.

This project is open-source and is not affiliated with, endorsed by, or associated with any of the mentioned services or platforms, including but not limited to Apple Music, Spotify, KKBox, Last.fm, Deezer, and YouTube Music. The use of their names, trademarks, or logos is solely to indicate compatibility or integration with these platforms and to enhance the user experience.

Any logos or trademarks displayed in this project and/or on the website remain the property of their respective owners.

Acknowledgement // End Note 🙃

• Uses yutipy 🎶
• Uses Pico CSS 🎨
• Powered by Render 🚀
• User Profile Icons by Rrgraph in CC Attribution License via SVG Repo 🧑‍🎨
• Thanks to OhaJoq for inspiring this project ✨
• Thanks to everyone who starred the repo—it means a lot! 🫂
• Uses Foundation for Emails for responsive email templates ✉️