From b05739b916f8876e0bf897dfcba49f7f89cf6f03 Mon Sep 17 00:00:00 2001
From: diyaa <info@diyaa.de>
Date: Mon, 23 Mar 2026 17:04:23 +0100
Subject: [PATCH] update README

---
 README.md | 373 +++++++-----------------------------------------------
 1 file changed, 49 insertions(+), 324 deletions(-)

diff --git a/README.md b/README.md
index 140c591..7846d7e 100644
--- a/README.md
+++ b/README.md
@@ -1,362 +1,87 @@
 # Velora Player
 
-إضافة ووردبريس توفّر مشغّل صوت حديث مع دعم:
+إضافة ووردبريس تضيف مشغّل صوت أنيق يمكن إدراجه داخل المحرر أو عبر `shortcode`.
 
-- بلوك
-- Gutenberg
-- shortcode
-- ثيمات جاهزة
-- لوحة إعدادات
-- تتبّع بسيط لعدد مرات التشغيل
+## ماذا تفعل الإضافة؟
 
-## نظرة سريعة
+- تعرض ملف صوتي واحد أو `playlist`
+- تعمل داخل Gutenberg كبلوك
+- تعمل أيضًا عبر `shortcode`
+- تدعم صورة غلاف وعنوان للمسار
+- تحتوي على ثيمات جاهزة
+- تسجّل عدد مرات التشغيل بشكل بسيط
 
-هذه الإضافة تبني مشغّل صوت مخصص يمكن استخدامه داخل محرر ووردبريس أو عبر
-`shortcode`
-في الصفحات والمقالات.  
-المشغّل يدعم صورة غلاف، عنوان للمسار الصوتي، شريط تقدّم، زر تشغيل وإيقاف، وثيمات عرض مختلفة.  
-كما تحتوي الإضافة على نظام تحليلات بسيط يحسب عدد مرات التشغيل لكل ملف صوتي.
+## طريقة الاستخدام
 
-## الميزات الرئيسية
+### 1. من محرر ووردبريس
 
-- بلوك مخصص داخل محرر ووردبريس باسم
-`Velora Player`
-- دعم العرض الديناميكي من السيرفر
-- دعم الإدراج باستخدام
-`[audio_player]`
-- ثلاث ثيمات جاهزة:
-`modern-dark`
-،
-`glassmorphism`
-،
-`podcast-style`
-- إعدادات عامة للتحكم في الألوان، الحواف، والثيم الافتراضي
-- صفحة تحليلات داخل لوحة التحكم
-- واجهة
-`REST API`
-لتسجيل التشغيلات
+- افتح الصفحة أو المقالة
+- أضف بلوك `Velora Player`
+- اختر الملف الصوتي
+- أضف العنوان وصورة الغلاف إذا رغبت
+- اختر الثيم أو اترك الإعداد الافتراضي
+- انشر الصفحة
 
-## كيف تعمل الإضافة
+### 2. باستخدام shortcode
 
-### 1. ملف التشغيل الرئيسي
-
-الملف:
-`modern-audio-player.php`
-
-وظيفته:
-
-- تعريف معلومات الإضافة
-- تعريف الثوابت الأساسية
-- تحميل الكلاسات
-- تنفيذ
-`activation hook`
-لإنشاء الإعدادات الافتراضية وجدول التحليلات
-- تشغيل الكلاس الرئيسي
-
-### 2. الكلاس الرئيسي
-
-الملف:
-`includes/class-plugin.php`
-
-وظيفته:
-
-- تهيئة الخدمات الأساسية:
-  - الإعدادات
-  - لوحة التحكم
-  - الـ shortcode
-  - REST API
-- تحميل الترجمة
-- تسجيل البلوك من خلال
-`block.json`
-- استخدام
-`render_callback`
-لعرض المشغّل من السيرفر
-
-### 3. الإعدادات
-
-الملف:
-`includes/class-settings.php`
-
-يحتوي على:
-
-- القيم الافتراضية للإضافة
-- قراءة الإعدادات من قاعدة البيانات
-- تنظيف القيم قبل الحفظ
-
-الإعدادات المتوفرة:
-
-- الثيم الافتراضي
-- الثيمات المفعّلة
-- لون التمييز
-- لون الخلفية
-- لون النص
-- درجة استدارة الحواف
-- إظهار صورة الغلاف أو إخفاؤها
-
-### 4. لوحة التحكم
-
-الملف:
-`admin/class-admin.php`
-
-يوفّر صفحتين داخل لوحة تحكم ووردبريس:
-
-- صفحة إعدادات
-- صفحة تحليلات
-
-ومن خلال صفحة الإعدادات يمكن التحكم في المظهر العام لكل المشغلات، بينما تعرض صفحة التحليلات عدد المسارات المسجّلة وإجمالي التشغيلات وأشهر الملفات الصوتية.
-
-### 5. العرض
-
-الملف:
-`includes/class-renderer.php`
-
-هذا الملف هو المسؤول عن بناء
-HTML
-الخاص بالمشغّل.
-
-أهم ما يفعله:
-
-- يجهّز الخصائص القادمة من البلوك أو الـ shortcode
-- يطبّق الثيم الافتراضي إذا لزم الأمر
-- يبني متغيرات
-CSS
-اعتمادًا على إعدادات الإضافة
-- يضيف بيانات التحليلات داخل
-`data-* attributes`
-- يعرض نسخة معاينة داخل المحرر إذا لم يتم اختيار ملف صوتي بعد
-- يحمّل ملفات الواجهة الأمامية عند العرض الديناميكي أو عند استخدام الـ shortcode
-
-### 6. الـ shortcode
-
-الملف:
-`includes/class-shortcode.php`
-
-يسجّل
-`[audio_player]`
-
-الخصائص المدعومة:
-
-- `src`
-- `title`
-- `image`
-- `theme`
-
-مثال:
+استخدم:
 
 ```text
 [audio_player src="https://example.com/audio.mp3" title="Episode 1" image="https://example.com/cover.jpg" theme="glassmorphism"]
 ```
 
-إذا لم يتم تمرير
-`theme`
-فسيتم استخدام الثيم الافتراضي من إعدادات الإضافة.
+### 3. استخدام Playlist داخل shortcode
 
-### 7. التحليلات
-
-الملف:
-`includes/class-analytics.php`
-
-وظيفته:
-
-- إنشاء جدول خاص في قاعدة البيانات عند تفعيل الإضافة
-- إنشاء
-`hash`
-ثابت لكل رابط صوتي
-- تسجيل كل تشغيل في قاعدة البيانات
-- إرجاع ملخص عام
-- إرجاع أكثر الملفات تشغيلًا
-
-اسم الجدول يكون بصيغة:
+يمكن تمرير `playlist` كسطور، وكل سطر بهذا الشكل:
 
 ```text
-{wp_prefix}map_analytics
+العنوان|رابط الصوت|رابط الصورة
 ```
 
-كل سجل يحتوي على معلومات مثل:
-
-- رابط الملف الصوتي
-- عنوانه
-- عدد مرات التشغيل
-- آخر وقت تشغيل
-
-### 8. واجهة REST API
-
-الملف:
-`includes/class-rest-api.php`
-
-تسجّل المسار التالي:
+مثال:
 
 ```text
-/wp-json/map/v1/track-play
+[audio_player playlist="Episode 1|https://example.com/ep1.mp3|https://example.com/ep1.jpg
+Episode 2|https://example.com/ep2.mp3|https://example.com/ep2.jpg" theme="podcast-style"]
 ```
 
-الطلب من نوع:
+إذا تم استخدام `playlist` فسيتم تشغيل المسارات من داخل نفس المشغّل.
 
-`POST`
+## الخيارات المتاحة في shortcode
 
-ويستقبل:
-
-- `src`
-- `title`
-- `hash`
-- `nonce`
-
-قبل تسجيل التشغيل يتم التحقق من:
-
-- وجود القيم المطلوبة
-- صحة
-`hash`
-- صحة
-`nonce`
-
-### 9. جافاسكربت الواجهة
-
-الملف:
-`assets/js/player.js`
-
-هذا الملف يدير سلوك المشغّل على الواجهة، مثل:
-
-- تشغيل وإيقاف الصوت
-- تحديث الوقت الحالي والمدة
-- تحديث شريط التقدم
-- الانتقال داخل الملف الصوتي
-- إرسال أول تشغيل فقط إلى
-`REST API`
-لكل نسخة من المشغّل داخل الصفحة
-
-### 10. بلوك المحرر
-
-الملف:
-`assets/js/block-editor.js`
-
-هذا الملف يسجل البلوك داخل المحرر ويضيف:
-
-- اختيار ملف صوتي من المكتبة
-- إدخال عنوان المسار
-- اختيار صورة غلاف
-- تفعيل أو تعطيل الثيم العام
-- اختيار ثيم مخصص
-- معاينة مباشرة باستخدام
-`ServerSideRender`
-
-### 11. التنسيق
-
-الملف:
-`assets/css/player.css`
-
-يحتوي على تنسيقات المشغّل، والثيمات المختلفة، والاستجابة للشاشات الصغيرة.
-
-## طريقة الاستخدام
-
-### استخدام البلوك
-
-من داخل محرر ووردبريس:
-
-1. أضف بلوك
-`Velora Player`
-2. اختر الملف الصوتي
-3. أضف العنوان وصورة الغلاف
-4. حدّد هل تريد استخدام الثيم العام أو ثيم مخصص
-
-### استخدام shortcode
-
-مثال بسيط:
-
-```text
-[audio_player src="https://example.com/audio.mp3" title="My Track"]
-```
-
-مثال كامل:
-
-```text
-[audio_player src="https://example.com/audio.mp3" title="Podcast Episode" image="https://example.com/image.jpg" theme="podcast-style"]
-```
+- `src` رابط الملف الصوتي
+- `title` عنوان المسار
+- `image` صورة الغلاف
+- `playlist` قائمة تشغيل
+- `theme` الثيم
 
 ## الثيمات المتوفرة
 
-### modern-dark
+- `modern-dark`
+- `glassmorphism`
+- `podcast-style`
 
-ثيم داكن عالي التباين مناسب للتصميمات الحديثة.
+## الإعدادات
 
-### glassmorphism
+من لوحة التحكم:
 
-ثيم شفاف بتأثير زجاجي وخلفية ضبابية.
+`Velora Player > Design Settings`
 
-### podcast-style
+يمكنك تعديل:
 
-ثيم أقرب لعرض حلقات البودكاست والمحتوى التحريري.
+- الثيم الافتراضي
+- الألوان
+- الحواف والمسافات
+- إظهار صورة الغلاف
 
-## تدفق العمل داخل الإضافة
+## التحليلات
 
-بشكل مبسط، التسلسل كالتالي:
+من لوحة التحكم:
 
-1. يتم تحميل الإضافة من الملف الرئيسي.
-2. يتم تسجيل البلوك والـ shortcode وصفحات الإدارة.
-3. عند إدراج المشغّل، يتم تمرير الخصائص إلى
-`Renderer`
-4. يتم إنشاء
-HTML
-وبيانات التتبع.
-5. في الواجهة، يتولى
-`player.js`
-تشغيل الصوت وتحديث الواجهة.
-6. عند أول تشغيل، يتم إرسال طلب إلى
-`REST API`
-7. تقوم طبقة التحليلات بتحديث قاعدة البيانات.
+`Velora Player > Analytics`
 
-## بنية الملفات
+ستجد:
 
-```text
-modern-audio-player/
-├── modern-audio-player.php
-├── uninstall.php
-├── README.md
-├── admin/
-│   └── class-admin.php
-├── includes/
-│   ├── class-plugin.php
-│   ├── class-settings.php
-│   ├── class-renderer.php
-│   ├── class-shortcode.php
-│   ├── class-rest-api.php
-│   └── class-analytics.php
-├── blocks/
-│   └── block.json
-└── assets/
-    ├── css/
-    │   ├── player.css
-    │   └── editor.css
-    └── js/
-        ├── player.js
-        ├── block-editor.js
-        ├── player.asset.php
-        └── block-editor.asset.php
-```
-
-## ملاحظات مهمة
-
-- الإضافة تعتمد على العرض الديناميكي، لذلك دالة
-`save`
-داخل البلوك ترجع
-`null`
-- ملفات الواجهة يتم تحميلها عبر
-`block.json`
-وميتاداتا الأصول
-- عند استخدام الـ shortcode يتم تحميل ملفات الواجهة أيضًا من خلال
-`Renderer::enqueue_block_assets()`
-
-## إزالة الإضافة
-
-يوجد ملف:
-`uninstall.php`
-
-ويمكن استخدامه لاحقًا لتنظيف بيانات الإضافة عند الحذف النهائي إذا أردت توسيع سلوك الإزالة.
-
-## ملخص
-
-هذه الإضافة مناسبة عندما تحتاج إلى:
-
-- مشغّل صوت مخصص بدل المشغّل الافتراضي
-- دعم للمحرر الحديث
-- تخصيص مظهر عام على مستوى الموقع
-- تتبّع بسيط لمرات التشغيل بدون نظام تحليلات معقّد
+- إجمالي التشغيلات
+- أكثر الملفات تشغيلًا
+- ملخصًا بسيطًا لاستخدام المشغّل