Upload fake_audio_cutter_demo.txt

fake_audio_cutter_demo.txt

@@ -0,0 +1,179 @@
+
+
+فائل انفارمیشن بیج اور کلوز کنٹرول | Audio Info Badge & Close Button
+مقصد اور کام: جیسے ہی کوئی آڈیو فائل اپلوڈ یا لوڈ ہوتی ہے، سب سے اوپر یہ بیج نمودار ہوتا ہے۔ اس کے بائیں جانب میوزک کا ویکٹر آئیکن اور ساتھ آڈیو کا نام ظاہر ہوتا ہے۔ فائل کے نام کے ساتھ آڈیو کا فارمیٹ اور سیمپل ریٹ (جیسے 24kHz Mono WAV) دکھائی دیتا ہے۔
+کلوز بٹن (Close 'X' Icon): بیج کے دائیں کونے پر ایک گول 'X' کراس بٹن ہوتا ہے۔
+تکنیکی منطق (Behavior & Logic): اس کراس بٹن پر کلک کرنے سے موجودہ آڈیو فوری طور پر میموری سے ان لوڈ ہو جاتی ہے، پلیئر رک جاتا ہے، تمام ٹیمپریری آبجیکٹ یو آر ایل (Blob URLs) میموری سے خارج (Revoke) کر دیے جاتے ہیں، اور ویوفارم کارڈ غائب ہو کر اصل ڈراپ زون حالت میں واپس چلا جاتا ہے۔
+متحرک ویوفارم کینوس اور پلے ہیڈ | Waveform Canvas & Playhead Engine
+مقصد اور کام: یہ اسٹوڈیو کا مرکزی ویژول ٹریک ہے۔ ایچ ٹی ایم ایل کینوس (HTML5 Canvas) کے ذریعے آڈیو کے ایمپلیٹیوڈ ڈیٹا کی بنیاد پر خوبصورت عمودی بارز بنتی ہیں جن کے کونے گول (Rounded) ہوتے ہیں اور درمیان میں ایک باریک سنٹرل بیس لائن ہوتی ہے۔
+پلے ہیڈ (Playhead Indicator): ویوفارم کے اوپر ایک باریک نیلی لکیر لائیو حرکت کرتی ہے جو آڈیو کے موجودہ پلے بیک ٹائم کو فیصد کے حساب سے ظاہر کرتی ہے۔
+اسکرول فرینڈلی ٹچ سسٹم: ٹریک پر خاص طور پر touch-action: pan-y لاگو ہوتا ہے جس کی بدولت موبائل اور ٹچ اسکرین پر اوپر نیچے اسکرولنگ بغیر کسی رکاوٹ کے کام کرتی ہے اور ویوفارم پر اسکرول کرنے سے ٹچ بلاک نہیں ہوتا۔
+سیکنگ (Direct Waveform Seeking): صارف ویوفارم کے کسی بھی حصے پر کلک یا ٹیپ کر کے آڈیو کو فوری اس مقام پر لے جا سکتا ہے۔
+ڈریگ ایبل سلیکشن اوورلے اور ہینڈلز | Draggable Selection Overlay & Trimming Handles
+مقصد اور کام: جب آڈیو کو کٹ کرنا مقصود ہو تو ویوفارم کے اوپر ایک شفاف رنگین سلیکشن ونڈو ظاہر ہوتی ہے۔ اس ونڈو کے بائیں جانب اسٹارٹ ہینڈل اور دائیں جانب اینڈ ہینڈل موجود ہوتا ہے۔
+ہینڈلز کی لچک: صارف شروع یا آخر کے ہینڈل کو ماؤس یا انگلی سے پکڑ کر آسانی سے دائیں بائیں سرکا سکتا ہے۔
+پوری سلیکشن کا تبادلہ: دونوں ہینڈلز کے درمیانی حصے کو پکڑ کر پوری سلیکشن ونڈو کو ایک ساتھ آگے یا پیچھے سلائیڈ کیا جا سکتا ہے بغیر اس کے مجموعی دورانیے کو تبدیل کیے۔
+سیلیکشن ڈیوریشن پل (Selection Duration Pill): ٹائم رو میں ایک سرخ یا نمایاں بیج نمودار ہوتا ہے جو ریئل ٹائم میں دکھاتا ہے کہ منتخب کردہ حصہ کتنے سیکنڈ یا منٹ کا ہے۔
+پوائنٹر کیپچر (Pointer Capture Safety): ہینڈل ڈریگ کرتے وقت براؤزر ایونٹ کو کیپچر رکھتا ہے تاکہ اگر ماؤس کینوس سے باہر بھی نکل جائے تو ڈریگنگ نہ ٹوٹے اور نہ ہی کوئی ایرر آئے۔
+اسپیکر آئیکن اور ٹوگل میوٹ بٹن | Speaker Icon & Toggle Mute Control
+مقصد اور کام: یہ کنٹرول پلے بیک بار کے بائیں جانب واقع ہوتا ہے۔ اس کا مقصد ایک کلک پر آڈیو کی آواز کو بغیر روکے فوراً بند (Mute) یا بحال (Unmute) کرنا ہے۔
+ویژول اسٹیٹ: جب آواز آن ہو تو اسپیکر سے نکلتی لہروں والا ویکٹر آئیکن ظاہر رہتا ہے۔ جب صارف اس پر کلک کرتا ہے تو اسپیکر کے اوپر کراس لکیر والا میوٹ آئیکن آ جاتا ہے۔
+تکنیکی منطق: یہ سسٹم آڈیو عنصر کی پراپرٹی audio.muted کو الٹ دیتا ہے اور پلے بیک رفتار یا ٹائم اسٹیمپ کو چھیڑے بغیر آواز کو بند یا آن کر دیتا ہے۔
+پلے بیک اسپیڈ بٹن | Playback Speed Cycle Pill
+مقصد اور کام: یہ ایک بیضوی (Pill) بٹن ہے جس پر موجودہ پلے بیک رفتار درج ہوتی ہے، جیسے 1.0x۔
+تکنیکی منطق اور سائیکل: جب صارف اس پر بار بار کلک کرتا ہے تو یہ ایک پیشگی ترتیب شدہ لسٹ کے مطابق رفتار کو خودکار تبدیل کرتا ہے:
+نارمل رفتار: 1.0x
+تیز رفتار: 1.25x
+مزید تیز: 1.5x
+دگنی رفتار: 2.0x
+دھیمی رفتار: 0.75x
+فائدہ: اس سے لمبی گفتگو یا حوالہ جاتی آواز کو تیزی سے سن کر مطلوبہ الفاظ یا خاموشیاں باآسانی تلاش کی جا سکتی ہیں۔
+ریوائنڈ کنٹرول بٹن | Rewind Control Button (-3s / -5s)
+مقصد اور کام: یہ بٹن آڈیو کو موجودہ پوزیشن سے چند سیکنڈ پیچھے لے جانے کے لیے استعمال ہوتا ہے (ڈیفالٹ تین یا پانچ سیکنڈ)۔ اس پر بائیں جانب مڑے ہوئے دوہرے تیروں کا ویکٹر آئیکن بنا ہوتا ہے۔
+تکنیکی منطق: جب اس پر کلک کیا جاتا ہے تو آڈیو کے موجودہ ٹائم میں سے سیکنڈز منفی ہو جاتے ہیں۔ اگر کراپ موڈ فعال ہو تو یہ ریوائنڈ ہوتے وقت سلیکشن کے شروع والے نقطے سے پیچھے نہیں جاتا تاکہ آڈیو کٹ رینج کے اندر ہی رہے۔
+آڈیو پلے اور پاز بٹن | Audio Play & Pause Master Button
+مقصد اور کام: یہ کنٹرول پینل کا سب سے نمایاں گول بٹن ہے جس کے اندر خوبصورت گریڈینٹ رنگ موجود ہوتا ہے۔
+ویژول ٹوگل: جب آڈیو رکی ہوئی ہو تو مثلث شکل کا پلے (Play) آئیکن نظر آتا ہے۔ جب آڈیو چل رہی ہو تو فوری طور پر دو عمودی سلاخوں والا پاز (Pause) آئیکن نمودار ہو جاتا ہے۔
+کراپ رینج انٹیلی جنس: اگر کراپ موڈ آن ہو اور صارف پلے دبائے تو آڈیو منتخب کردہ رینج کے اسٹارٹ سے شروع ہوتی ہے۔ جیسے ہی پلے ہیڈ منتخب کردہ رینج کے آخری سرے تک پہنچتا ہے، آڈیو خودکار طور پر پاز ہو جاتی ہے اور پلے ہیڈ واپس سلیکشن کے آغاز پر سیٹ ہو جاتا ہے۔
+فارورڈ کنٹرول بٹن | Forward Control Button (+3s / +5s)
+مقصد اور کام: یہ بٹن آڈیو کو موجودہ پوزیشن سے چند سیکنڈ آگے لے جانے کے لیے استعمال ہوتا ہے۔ اس پر دائیں جانب رخ کیے ہوئے دوہرے تیروں کا ویکٹر آئیکن بنا ہوتا ہے۔
+تکنیکی منطق: یہ موجودہ ٹائم میں سیکنڈز کا اضافہ کرتا ہے۔ اگر کراپ موڈ آن ہو تو یہ سلیکشن کے آخری پوائنٹ سے آگے نہیں بڑھتا، جس سے صارف آسانی سے مخصوص الفاظ کو بار بار سن کر تسلی کر سکتا ہے۔
+کینچی والا کراپ موڈ بٹن | Scissors Crop Mode Toggle Button
+مقصد اور کام: یہ ٹرمنگ اسٹوڈیو کا گیٹ وے بٹن ہے۔ اس پر ایک خوبصورت باریک کینچی (Scissors) کا ویکٹر آئیکن بنا ہوتا ہے۔
+ویژول ایکٹیویشن: جب اس پر کلک کیا جاتا ہے تو یہ ایکٹو اسٹیٹ میں چلا جاتا ہے (سرخ یا نمایاں بیک گراؤنڈ کے ساتھ چمکتا ہے)۔
+انٹرفیس کی تبدیلی: کینچی پر کلک ہوتے ہی:
+نارمل ایکشن کنٹرولز وقتی طور پر چھپ جاتے ہیں۔
+ویوفارم پر کراپ سلیکشن اوورلے اور دونوں سائیڈوں کے ہینڈلز روشن ہو جاتے ہیں۔
+سلیکشن ڈیوریشن پل ظاہر ہو جاتی ہے۔
+اس بٹن کے ساتھ فوری طور پر دو نئے ایکشن پلز (Trim اور Cancel) نمودار ہو جاتے ہیں۔
+اگر کینچی کے بٹن کو دوبارہ دبایا جائے تو کراپ موڈ بند ہو جاتا ہے اور اسکرین نارمل حالت میں واپس آ جاتی ہے۔
+ٹرم اور کینسل ایکشن پلز | Trim & Cancel Action Pills
+ظہور کی شرط: یہ دونوں بٹنز صرف اسی وقت اسکرین پر آتے ہیں جب کینچی والے بٹن کے ذریعے کراپ موڈ آن کیا گیا ہو۔
+ٹرم بٹن (Trim Selection Pill):
+اس پر سبز رنگ اور چیک مارک (Checkmark) کا آئیکن ہوتا ہے۔
+جیسے ہی صارف اس پر کلک کرتا ہے، میموری کے اندر موجود ویب آڈیو بفر سے سلیکٹ کیا گیا حصہ ریاضیاتی طور پر کاٹ کر ایک نیا 16-Bit PCM WAV آڈیو بنا دیا جاتا ہے۔
+کٹی ہوئی آڈیو فوری طور پر ویوفارم پر لوڈ ہو جاتی ہے، نیا دورانیہ اپڈیٹ ہو جاتا ہے، کراپ موڈ بند ہو جاتا ہے، اور یہ نئی کٹی ہوئی آڈیو وائس کلوننگ یا ڈاؤنلوڈ کے لیے تیار ہو جاتی ہے۔
+کینسل بٹن (Cancel Pill):
+اس پر کراس کا آئیکن ہوتا ہے۔
+اس پر کلک کرنے سے سلیکشن ونڈو ختم ہو جاتی ہے، کوئی آڈیو کٹ نہیں ہوتی، اور صارف واپس نارمل ویوفارم موڈ میں آ جاتا ہے۔
+انڈو اور بحالی کا بٹن | Undo & Revert Trim Dynamic Button
+ظہور کی شرط: یہ بٹن عام حالت میں بالکل پوشیدہ (Hidden) رہتا ہے۔ یہ صرف اور صرف اس وقت نمودار ہوتا ہے جب آڈیو کو کینچی کے ذریعے کامیابی سے ٹرم کر دیا گیا ہو۔
+مقام اور بناوٹ: یہ کینچی والے بٹن کے عین بائیں جانب نمودار ہوتا ہے۔ اس پر گول گھومے ہوئے مڑے تیر کا ویکٹر آئیکن بنا ہوتا ہے۔
+تکنیکی منطق: اگر صارف سے غلطی سے غلط حصہ کٹ جائے تو پریشان ہونے کی ضرورت نہیں۔ اس انڈو بٹن پر ایک کلک کرنے سے سسٹم اصل (اورینجیل) آڈیو کو فوری بحال کر دیتا ہے، نیا ویوفارم دوبارہ کھینچتا ہے، اور یہ بٹن خود بخود واپس غائب ہو جاتا ہے۔
+آڈیو ڈاؤنلوڈ بٹن | Download Audio Direct Button
+مقصد اور کام: پلے بیک پینل کے دائیں جانب تیر کا نشان نیچے کی طرف بنا ہوتا ہے جو ٹرے کے اندر اتر رہا ہوتا ہے۔
+تکنیکی منطق: اس پر کلک کرتے ہی براؤزر میں کسی سرور کال کے بغیر، کلائنٹ سائیڈ پر بنی ہوئی موجودہ آڈیو فائل (خواہ وہ اوریجنل ہو یا کینچی سے ٹرم کی ہوئی ہو) ایک معیاری WAV فائل کے طور پر صارف کی ڈیوائس پر ڈاؤنلوڈ ہو جاتی ہے۔ ڈاؤنلوڈ ہونے والی فائل کا نام خودکار طور پر _trimmed.wav کے سابقے کے ساتھ محفوظ ہوتا ہے۔
+لائٹ اور ڈارک موڈ مطابقت | Adaptive Contrast & Infinite Click Reliability
+ڈارک موڈ ویژول: گہرے پس منظر پر لومینس پرپل ویوفارم، سفید ہینڈل بارز اور نیلا چمکدار پلے ہیڈ ظاہر ہوتا ہے۔
+لائٹ موڈ ویژول: سفید پس منظر پر تمام فونٹ اور اعداد گہرے سیاہ/سلیٹ (#0f172a / #334155) رنگ میں تبدیل ہو جاتے ہیں تاکہ سفید پر ہلکا رنگ چھپ نہ جائے، اور ویوفارم بارز گہرے انڈیگو رنگ میں تبدیل ہو جاتی ہیں۔ تھیم بدلتے ہی ویوفارم بغیر پیج ریفریش کیے خود کو فوری نئے رنگ میں ری ڈرا کر لیتا ہے۔
+لامحدود کلک برداشت (Infinite Click Stress Tolerance): تمام بٹنز میں ری اینٹرینسی تالے (Re-entrancy Locks) لگائے جاتے ہیں تاکہ اگر کوئی صارف ایک سیکنڈ میں درجنوں بار بٹن پر کلک کرے یا آن آف کرے تو نہ کوڈ اٹکے، نہ براؤزر کریش ہو، اور نہ ہی آڈیو بفر خراب ہو۔
+
+--------------------------
+جامع انٹرفیس اسٹرکچر ٹری | Universal Component & DOM Tree Structure
+
+یہ اسٹوڈیو کا مکمل اسٹرکچرل اور ہائیرارکل (Hierarchical) خاکہ ہے جو ظاہر کرتا ہے کہ تمام ایچ ٹی ایم ایل عناصر، ڈریگ ایبل کنٹینرز، ٹائم لیبلز اور کنٹرول بٹنز کس طرح ایک دوسرے کے اندر ترتیب دیے گئے ہیں:
+
+└── Waveform Card Master Container (.waveform-card)
+    │
+    ├── Top Badge & Information Row (.waveform-top-row)
+    │   └── File Information Chip (.waveform-badge)
+    │       ├── Music Note Icon (Vector SVG)
+    │       ├── File Name Label (#fileName)
+    │       ├── Audio Format Tag (#formatTag) [e.g. 24kHz Mono WAV]
+    │       └── Remove / Close Button (#closeBtn) [Vector SVG 'X']
+    │
+    ├── Waveform Track Canvas Box (.waveform-canvas-box) [touch-action: pan-y]
+    │   ├── High-DPI Waveform Canvas (#canvas) [Rounded Bars + Baseline]
+    │   │
+    │   ├── Draggable Selection Window (.waveform-selection-overlay)
+    │   │   ├── Start Drag Handle (.waveform-handle.start)
+    │   │   │   └── Handle Vertical Grab Bar (.waveform-handle-bar)
+    │   │   │
+    │   │   └── End Drag Handle (.waveform-handle.end)
+    │   │       └── Handle Vertical Grab Bar (.waveform-handle-bar)
+    │   │
+    │   └── Active Playhead Indicator (.wf-playhead) [Real-time Dynamic Left %]
+    │
+    ├── Time & Selection Status Row (.waveform-time-row)
+    │   ├── Current Playback Time (#currentTime) [00:00.0]
+    │   │
+    │   ├── Selection Duration Pill (.crop-duration-pill) [Appears in Crop Mode]
+    │   │   ├── Mini Scissors Icon (Vector SVG)
+    │   │   └── Selection Span Label (#cropDurationText)
+    │   │
+    │   └── Total Audio Duration (#totalDuration) [00:00.0]
+    │
+    └── Master Controls Bar (.waveform-controls)
+        │
+        ├── Left Group: Audio Properties (.ctrl-group)
+        │   ├── Toggle Mute Button (#volBtn)
+        │   │   ├── Volume High Icon (Vector SVG)
+        │   │   └── Volume Muted Icon (Vector SVG)
+        │   └── Playback Speed Pill (#speedBtn) [Cycles: 1.0x ➔ 1.25x ➔ 1.5x ➔ 2.0x ➔ 0.75x]
+        │
+        ├── Center Group: Transport Controls (.ctrl-group)
+        │   ├── Rewind Button (#rewindBtn) [-3s / -5s Jump Back]
+        │   │
+        │   ├── Master Play / Pause Button (#playBtn) [Primary Gradient Circle]
+        │   │   ├── Play Triangle Icon (Vector SVG)
+        │   │   └── Pause Dual Bars Icon (Vector SVG)
+        │   │
+        │   └── Forward Button (#forwardBtn) [+3s / +5s Jump Forward]
+        │
+        └── Right Group: Scissors Editing & Action Controls (.ctrl-group)
+            │
+            ├── Normal State Controls (#normalControls) [Active by Default]
+            │   ├── Undo / Revert Trim Button (#undoBtn) [Hidden until trimmed]
+            │   ├── Scissors Crop Mode Button (#cutBtn) [Scissors SVG]
+            │   └── Download Audio Button (#downloadBtn) [Download SVG]
+            │
+            └── Crop Active Action Group (#cropControls) [Active in Scissors Mode]
+                ├── Trim Selection Pill (#applyTrimBtn) [Checkmark SVG + 'Trim']
+                └── Cancel Crop Pill (#cancelTrimBtn) [Cross SVG + 'Cancel']
+
+لائف سائیکل اور ڈیٹا فلو ٹری | Audio Lifecycle & Data Processing Flow Tree
+
+یہ فلو ٹری واضح کرتا ہے کہ کس طرح ایک آڈیو کلائنٹ سائیڈ میموری میں ڈی کوڈ ہوتی ہے، ویوفارم لہروں میں تبدیل ہوتی ہے، اور کینچی کے ذریعے بغیر سرور کے کاٹی جاتی ہے:
+
+[Audio Input Source] (File Upload / Drag & Drop / Recorded Blob)
+  │
+  ▼
+[Web Audio API Engine] (AudioContext.decodeAudioData)
+  │
+  ├──► [Raw PCM Channel Data Extraction]
+  │      └──► [Canvas Waveform Calculation] (RMS / Peak Bars + Baseline Draw)
+  │
+  └──► [Audio Playback Element Binding]
+         ├──► [Playhead Sync Engine] (timeupdate ➔ percentage position)
+         └──► [Time Display Formatter] (Current Time / Total Duration)
+  │
+  ▼
+[User Clicks Scissors Button ✂️]
+  │
+  ├──► Normal Controls Hidden (#normalControls ➔ display: none)
+  ├──► Crop Pills Shown (#cropControls ➔ display: flex)
+  ├──► Selection Overlay Rendered (with Start & End Handles)
+  └──► Live Pointer Listeners Active (Drag Start / Drag End / Move Box)
+  │
+  ▼
+[User Clicks 'Trim Selection' Pill]
+  │
+  ├──► [In-Memory 16-Bit PCM WAV Slicing] (audioBufferToWavBlob)
+  │      ├── Start Frame = Math.floor(cropStart * sampleRate)
+  │      ├── End Frame = Math.floor(cropEnd * sampleRate)
+  │      └── RIFF/WAVE 44-byte Header + PCM Data Binary Assembly
+  │
+  ├──► [New Trimmed Blob Generation]
+  ├──► [Audio Player & Canvas Reloaded with Trimmed Audio]
+  ├──► [Undo Button (#undoBtn) Activated & Rendered Visible]
+  └──► [Crop Overlay Deactivated ➔ Normal Controls Restored]
+  │
+  ▼
+[User Clicks 'Undo' Button (Optional Revert)]
+  │
+  ├──► Original Untrimmed Blob Restored to Player & Canvas
+  └──► Undo Button (#undoBtn) Hidden Automatically
+
+
+
+