SimpleSyntax

SimpleSyntax is a simple CSS-inspired Python media library built around:

• yt-dlp
• FFmpeg
• gallery-dl

Its main goal is to provide a simple API for downloading media and extracting metadata without requiring complicated downloader classes or configuration objects.

Installation

pip install SimpleSyntax

SimpleSyntax uses:

yt-dlp for video and supported metadata operations

gallery-dl for images and galleries

FFmpeg when media streams need to be merged



---

Main API

The main API is:

from SimpleSyntax import rz

rz({...}, url)

The value on the right side of every selector is a user-defined Python variable name.

Example:

from SimpleSyntax import rz

rz({
    "media[4]": "M"
}, "https://example.com/media")

print(M)

Here:

"media[4]" → M

means the downloaded media is made available through the variable M.

Another example:

from SimpleSyntax import rz

rz({
    "media[4]": "V",
    "title": "T",
    "creator": "C"
}, url)

print(V)
print(T)
print(C)

The user chooses the variable names.

SimpleSyntax does not force names such as:

video
title
creator
views

The right-side names can be different valid Python variable names.


---

Dictionary Order

The order of selectors inside the dictionary does not matter.

These are equivalent:

rz({
    "media[4]": "M",
    "title": "T",
    "creator": "C"
}, url)

and:

rz({
    "creator": "C",
    "media[4]": "M",
    "title": "T"
}, url)

SimpleSyntax identifies each operation from its selector.


---

Variable Assignment

SimpleSyntax uses the right side of each selector as the variable name exposed to the caller.

For example:

rz({
    "media[4]": "M"
}, url)

print(M)

The selector:

media[4]

defines what SimpleSyntax should retrieve.

The value:

M

defines the variable name that the user will use.

Multiple values can be requested together:

rz({
    "media[4]": "VIDEO",
    "title": "TITLE",
    "creator": "AUTHOR",
    "views": "VIEW_COUNT"
}, url)

print(VIDEO)
print(TITLE)
print(AUTHOR)
print(VIEW_COUNT)

No separate result dictionary is required for normal usage.


---

Video Selectors

video[N] explicitly selects a video/yt-dlp operation.

The quality mapping is fixed:

Selector	Meaning

video[0]	Best available audio
video[1]	360p
video[2]	480p
video[3]	720p
video[4]	1080p
video[5]	1440p
video[6]	Best available


Example:

from SimpleSyntax import rz

rz({
    "video[4]": "V"
}, url)

print(V)

video without [N] is invalid.


---

Video Quality Fallback

If the requested quality is unavailable, SimpleSyntax automatically tries the next lower available quality.

For example:

1080p
  ↓
720p
  ↓
480p
  ↓
360p

The operation should not fail merely because the requested quality is unavailable.


---

Media Selectors

media[N] automatically determines which media downloader should be used.

media[N]
   ↓
detect media type
   ├── VIDEO → yt-dlp
   └── IMAGE → gallery-dl

The quality mapping is:

Selector	Meaning

media[0]	Best available audio
media[1]	360p
media[2]	480p
media[3]	720p
media[4]	1080p
media[5]	1440p
media[6]	Best available


Example:

from SimpleSyntax import rz

rz({
    "media[4]": "M"
}, "https://example.com/media")

print(M)

For a video, [N] controls the requested video quality.

For an image, [N] does not resize or convert the image. gallery-dl downloads the original/available image quality.

media[N] does not mean downloading both a video and an image.


---

Media Fallback

media[N] uses automatic media detection.

The video path is attempted through yt-dlp first.

If the video operation fails, SimpleSyntax attempts the image/gallery operation through gallery-dl.

media[N]
   ↓
yt-dlp
   ↓
success?
 ├── YES → done
 └── NO
      ↓
gallery-dl
      ↓
success?
 ├── YES → done
 └── NO → failure

Cookie fallback is applied to both downloader types.


---

Image Selector

For direct image operations, use:

from SimpleSyntax import rz

rz({
    "image": "IMG"
}, "https://example.com/image")

print(IMG)

The image selector uses gallery-dl directly.

image[N] is invalid.


---

Metadata

SimpleSyntax supports the following metadata selectors:

Selector	Meaning

title	Title
creator	Creator/uploader/author
url	Page/video URL
views	View count
likes	Like count
comments	Comment count
duration	Duration
thumbnail	Thumbnail URL


Example:

from SimpleSyntax import rz

rz({
    "title": "T",
    "creator": "C",
    "url": "U",
    "views": "V",
    "likes": "L",
    "comments": "CM",
    "duration": "D",
    "thumbnail": "TH"
}, url)

print(T)
print(C)
print(U)
print(V)
print(L)
print(CM)
print(D)
print(TH)

The right-side names are completely user-defined.


---

Media and Metadata Together

Media and metadata can be requested in the same rz() call.

from SimpleSyntax import rz

rz({
    "media[4]": "M",
    "title": "T",
    "creator": "C",
    "url": "U",
    "views": "V",
    "likes": "L",
    "comments": "CM",
    "duration": "D",
    "thumbnail": "TH"
}, url)

print(M)
print(T)
print(C)
print(U)
print(V)
print(L)
print(CM)
print(D)
print(TH)


---

Cookies

SimpleSyntax uses the variable:

ReiZyuki

Example:

ReiZyuki = [
    "/storage/emulated/0/Download/youtube.txt",
    "/storage/emulated/0/Download/instagram.txt",
    "/storage/emulated/0/Download/reddit.txt"
]

The user does not pass cookies as an argument to rz().

Correct:

from SimpleSyntax import rz

ReiZyuki = [
    "/storage/emulated/0/Download/instagram.txt"
]

rz({
    "image": "IMG"
}, url)

print(IMG)

There is no need for:

rz({...}, url, cookies=ReiZyuki)


---

Cookie Fallback

SimpleSyntax always attempts the operation without cookies first.

Request
   ↓
No-cookie attempt
   ↓
Success?
 ┌───────┴───────┐
 YES             NO
 ↓                ↓
DONE          ReiZyuki
                  ↓
             cookie #1
                  ↓
               works?
              /     \
            YES      NO
             ↓       ↓
           DONE   cookie #2
                    ↓
                  ...

Rules:

1. Try without cookies first.


2. If successful, stop immediately.


3. If it fails, use the supplied ReiZyuki paths.


4. Test cookie files one-by-one.


5. The first working cookie is selected.


6. If all cookies fail, raise the original no-cookie error.



This applies to:

video downloads

image downloads

media operations

playlists

metadata extraction

supported yt-dlp operations

supported gallery-dl operations


SimpleSyntax does not:

scan random directories

invent cookie files

require specific cookie filenames

automatically search for cookies

hardcode website-specific cookie filenames


Only paths supplied by the user through ReiZyuki are candidates.


---

Observer

SimpleSyntax includes an Observer for ranking supplied cookie paths.

Observer can consider:

URL relevance

cookie filename relevance

previous successful cookie history


The Observer score is a ranking/relevance score.

It does not mean that a cookie is partially valid.

A cookie must still be tested by the actual downloader.

Example:

[Observer]

instagram.txt -> 78.85% match
youtube.txt   -> 21.25% match
reddit.txt    -> 20.00% match

Selected order:

1. instagram.txt
2. youtube.txt
3. reddit.txt

The highest-ranked cookie is tested first.


---

Playlist

Playlist syntax is fixed:

from SimpleSyntax import rz

rz({
    "playlist": "QUALITY:SKIP:COUNT"
}, playlist_url)

The quality mapping is:

Value	Meaning

0	Best available audio
1	360p
2	480p
3	720p
4	1080p
5	1440p
6	Best available


Example:

rz({
    "playlist": "4:5:10"
}, playlist_url)

This means:

4  → 1080p
5  → skip first 5 items
10 → download next 10 items

Therefore:

Items 1–5   → skipped
Items 6–15  → downloaded

Quality fallback also applies to playlist downloads.


---

Playlist + Media + Metadata

Playlist processing can be combined with media and metadata selectors.

from SimpleSyntax import rz

rz({
    "playlist": "4:5:10",
    "media[4]": "M",
    "title": "T",
    "creator": "C",
    "url": "U",
    "views": "V",
    "likes": "L",
    "comments": "CM",
    "duration": "D",
    "thumbnail": "TH"
}, playlist_url)

print(M)
print(T)
print(C)


---

FFmpeg

FFmpeg is used when required to merge separate video and audio streams.

SimpleSyntax avoids unnecessary re-encoding.

When compatible source streams are available, the downloader prefers:

H.264 / AVC video
AAC / M4A audio

and produces MP4 output when merging is required.

The goal is to preserve source quality while producing compatible media.


---

yt-dlp

yt-dlp handles video-based operations such as:

video[N]

video detection through media[N]

playlist downloads

supported metadata extraction



---

gallery-dl

gallery-dl handles:

image

image/gallery detection through media[N]


The user does not need to manually call gallery-dl when using media[N].


---

Default Download Directory

Downloaded media is stored by default in:

/storage/emulated/0/Download/ReiDownloader/


---

Complete Examples

Video Download

from SimpleSyntax import rz

rz({
    "video[4]": "V"
}, "https://example.com/video")

print(V)

Audio

from SimpleSyntax import rz

rz({
    "video[0]": "A"
}, "https://example.com/video")

print(A)

Automatic Media

from SimpleSyntax import rz

rz({
    "media[4]": "M"
}, "https://example.com/media")

print(M)

Image

from SimpleSyntax import rz

rz({
    "image": "IMG"
}, "https://example.com/image")

print(IMG)

Metadata

from SimpleSyntax import rz

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

print(T)
print(C)
print(V)

Cookies

from SimpleSyntax import rz

ReiZyuki = [
    "/storage/emulated/0/Download/instagram.txt"
]

rz({
    "image": "IMG"
}, "https://www.instagram.com/example/")

print(IMG)

Playlist

from SimpleSyntax import rz

rz({
    "playlist": "4:5:10"
}, "https://example.com/playlist")


---

Invalid Syntax

Invalid Video Selector

This is invalid:

rz({
    "video": "V"
}, url)

Use a quality selector:

rz({
    "video[4]": "V"
}, url)


---

Invalid Image Quality Selector

This is invalid:

rz({
    "image[4]": "IMG"
}, url)

Use:

rz({
    "image": "IMG"
}, url)


---

Invalid Quality

Quality values outside 0–6 are invalid.

For example:

rz({
    "video[10]": "V"
}, url)

is invalid.


---

Invalid Playlist Format

This is invalid:

rz({
    "playlist": "1080p:5:10"
}, url)

Use the numeric quality format:

rz({
    "playlist": "4:5:10"
}, url)


---

Quick Reference

Main API

from SimpleSyntax import rz

rz({...}, url)

Video

video[0] → audio
video[1] → 360p
video[2] → 480p
video[3] → 720p
video[4] → 1080p
video[5] → 1440p
video[6] → best

Media

media[0] → audio
media[1] → 360p
media[2] → 480p
media[3] → 720p
media[4] → 1080p
media[5] → 1440p
media[6] → best

Image

image

Metadata

title
creator
url
views
likes
comments
duration
thumbnail

Playlist

playlist = "QUALITY:SKIP:COUNT"

Cookies

ReiZyuki = [...]

Default Directory

/storage/emulated/0/Download/ReiDownloader/


---

Public API Principle

SimpleSyntax is designed around a small CSS-inspired API:

rz({...}, url)

Selectors describe what SimpleSyntax should do, while the right-side values define the variable names through which the requested values are made available to the caller.