SimpleSyntax

SimpleSyntax is a lightweight, CSS-selector-inspired Python library for downloading media and extracting metadata from various platforms.

It provides a clean, declarative API for media tasks with:

• 🎯 CSS-inspired selectors
• 🍪 Automatic cookie matching and fallback
• 📥 Video and media downloading
• 🖼️ Image fallback through gallery-dl
• 🧾 Metadata extraction
• 📋 Playlist downloading
• 🔄 Successful URL/cookie history
• 🐍 A simple Python API through rz()

Current Version

0.1.5

What's Fixed / Improved in 0.1.5

• Fixed caller-scope variable assignment so values returned by rz() are available directly in the user's Python scope.
• Fixed playlist request validation so QUALITY:SKIP:COUNT values such as "0:0:150" are correctly recognized as playlist configuration instead of being incorrectly validated as Python variable names.
• Fixed playlist downloads using the existing QUALITY:SKIP:COUNT syntax and verified playlist requests can reach the downloader correctly.
• Fixed metadata handling so extraction errors are printed as safe error messages instead of crashing the program with an unhandled exception.
• Improved metadata failure handling so a failed metadata extraction returns safely without breaking a successful media fallback operation.
• Improved cookie fallback handling with cookie ranking based on the target site's hostname and cookie filename.
• Added a 40% cookie-match threshold so unrelated cookie files are skipped.
• Added ordered cookie fallback attempts for matching cookie files.
• Added successful URL/cookie history support through the helper file.
• Preserved the ReiZyuki cookie-list API for user-supplied cookie files.
• Improved media fallback flow between video downloading and image downloading.
• Kept the CSS-inspired selector API and existing rz({...}, url) syntax unchanged.
• Metadata selectors continue to support title, creator, URL, views, likes, comments, duration, thumbnail, date, and live status.

Requirements

• Python >= 3.9
• yt-dlp
• gallery-dl
• ffmpeg (required for merging audio/video streams)

Installation

pip install simplesyntax

The package installs its Python dependencies automatically. ffmpeg should be available separately when media merging is required.

Basic Usage

SimpleSyntax uses a single entry point, rz, with a CSS-inspired selector syntax:

from simplesyntax import rz

url = "https://example.com/video"

rz({
    "video[3]": "my_video",
    "title": "video_title"
}, url)

print(f"Downloaded: {my_video}")
print(f"Title: {video_title}")

Selector Syntax

Media Selectors

Media selectors support a quality index from 0 to 6:

• video[N] — Downloads video/audio media.
• media[N] — Attempts video downloading first and falls back to image downloading if the video engine cannot download the media.

Quality Index

Index	Quality
0	Audio only
1	360p
2	480p
3	720p
4	1080p
5	1440p
6	Best quality

Example:

rz({"media[3]": "downloaded_media"}, url)
print(downloaded_media)

Metadata Selectors

The following metadata selectors are supported:

• title
• creator
• url
• views
• likes
• comments
• duration
• thumbnail
• date (YYYY/MM/DD)
• live

Example:

rz({
    "title": "title",
    "creator": "creator",
    "views": "views"
}, url)

print(title)
print(creator)
print(views)

Cookie & Fallback System

SimpleSyntax supports optional cookie files through a variable named ReiZyuki in the caller's scope:

ReiZyuki = [
    "/path/to/youtube.txt",
    "/path/to/instagram.txt",
    "/path/to/reddit.txt"
]

The fallback system:

1. Matches the target site's hostname against supplied cookie filenames.
2. Calculates a cookie match score.
3. Skips cookies below the 40% match threshold.
4. Tries the best matching cookie first.
5. Falls back to a no-cookie attempt when the matching cookie fails.
6. Continues with the next matching cookie when necessary.
7. Records successful URL/cookie associations in the helper history file.

No cookie files are scanned automatically; only paths supplied through ReiZyuki are used.

Cookie File Naming

For reliable cookie matching, keep each cookie filename based on the target website's domain name. SimpleSyntax compares the target URL hostname with the cookie filename using similarity matching.

Recommended examples:

https://www.youtube.com/...      → youtube.txt
https://www.instagram.com/...    → instagram.txt
https://www.reddit.com/...       → reddit.txt
https://www.tiktok.com/...       → tiktok.txt

Avoid unrelated or generic names such as cookies.txt, mycookie.txt, login.txt, or account1.txt when possible.

For best results, use the website/domain name as the filename followed by .txt.

Media Fallback

media[N] is designed for URLs where the normal video downloader may not be able to retrieve a video.

The flow is:

media[N]
   │
   ├── Try video download (yt-dlp)
   │
   └── If video download fails
           │
           └── Try image download (gallery-dl)

This means a platform response such as "No video formats found" from yt-dlp does not necessarily mean the overall media[N] operation cannot succeed. If gallery-dl can retrieve an image, the media fallback can still complete successfully.

Playlist Handling

Playlist downloads use the existing QUALITY:SKIP:COUNT syntax:

rz({"playlist": "3:0:5"}, url)

This downloads 5 items starting from index 0 using quality index 3 (720p).

Project & Creator

Project: SimpleSyntax
Creator / YouTube: ReiZyuki

SimpleSyntax is developed under the ReiZyuki name.

Bug Reports & Help

If you find a bug, need help using SimpleSyntax, or have a problem with a selector or downloader, contact:

Email: Azadofficial2026@gmail.com

When reporting an issue, it helps to include:

• Python version
• SimpleSyntax version
• Platform/URL type
• The selector you used
• The relevant error or terminal output

Please avoid sharing private cookie contents in bug reports.

Notes

Some platforms may still require valid cookies or may restrict automated access. A platform-side HTTP/API restriction does not necessarily indicate a SimpleSyntax selector or fallback error.

Cookie files are user-supplied and should be kept private. Never publish or share your cookie file contents.

---

Author / YouTube: ReiZyuki
Contact: Azadofficial2026@gmail.com
SimpleSyntax 0.1.5