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.3

What's Fixed / Improved in 0.1.3

• Fixed caller-scope variable assignment so values returned by rz() are available directly in the user's Python scope.
• 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.
• Playlist selector support remains available through QUALITY:SKIP:COUNT syntax.

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.

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.3