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 handling media tasks with automatic cookie fallback, metadata extraction, playlist handling, and image fallback support.

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

The library provides a single entry point, rz, using 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 fails.

Quality Index (N):

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

Metadata Selectors

The following metadata selectors are supported:

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

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.

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

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.

Author: ReiZyuki
SimpleSyntax 0.1.3