البدء السريع على Flutter
إضافة Flutter لنظامي Android و iOS قادمة قريبًا. وإلى أن تُنشر على pub.dev، استدعِ حزمتَي SDK الخاصتين بـ Android و Apple من شيفرة المنصّة في تطبيقك.
إضافة Flutter (plugin) المسمّاة quranlab_tajweedformer قادمة قريبًا. وهي ليست على pub.dev بعد: لا تُضفها إلى pubspec.yaml، ولا تكتب اعتمادية (dependency) من نوع git أو path تشير إليها. وستحمل هذه الصفحة سطر تثبيتها يوم نشرها.
الإضافة واجهة Dart واحدة لنظامي Android و iOS. وهي تغلّف حزمة SDK الخاصة بـ Android (ai.quranlab:tajweedformer على Maven Central) وحزمة SDK الخاصة بـ Apple (حزمة Swift المتاحة على github.com/Quran-Lab/tajweedformer-apple)، ولا تحتوي على نسخة من أيٍّ منهما.
إلى أن تُنشر
استخدم الـ SDK من شيفرة المنصّة في تطبيقك. توضع حزمة SDK الخاصة بـ Android في المجلد android، وحزمة SDK الخاصة بـ Apple في المجلد ios: وتجد في صفحتَي البدء السريع على Android والبدء السريع على Apple سطر التثبيت، ومكان المفتاح، والاستدعاءات الأربعة لكل جانب. وتصل شيفرة Dart في تطبيقك إليهما عبر قناة المنصّة (platform channel): MethodChannel، و EventChannel للمقاطع. ويستطيع مساعد برمجي أُعدّ بـمهارة Quran Lab أن يكتب هذا الجسر معك، وتحلّ الإضافة محلّه بعد صدورها.
ما تحتاجه الإضافة
- Flutter 3.41 أو أحدث.
- Android 8.0 (API 26) أو أحدث، على
arm64-v8aأوarmeabi-v7a. ويشغّل محاكي x86-64 المحرّكَ على المعالج المركزي. - iOS 15 أو أحدث على أجهزة Apple silicon، مع البناء باستخدام Xcode 16 أو أحدث.
- Swift Package Manager لبناء نسخة iOS. لا تُوزَّع حزمة SDK الخاصة بـ Apple إلا حزمةَ Swift، ولذلك لا تدعم الإضافة CocoaPods. و Swift Package Manager هو الخيار الافتراضي في Flutter منذ 3.44؛ وفي إصدار أقدم من Flutter، شغّل
flutter config --enable-swift-package-manager. - اتصال بالإنترنت مرة واحدة. يُنزَّل النموذج (56.5 ميغابايت) قبل الجلسة الأولى، ويُتحقَّق من كل ملف فيه، ثم يعمل بعد ذلك دون اتصال.
المفتاح
استخدم مفتاح تطبيقات للمنصّتين كلتيهما. معرّف التطبيق هو applicationId الخاص به في Gradle على Android، ومعرّف الحزمة (bundle id) على iOS. أبقِ المفتاح خارج مستودعك.
وإلى أن تصدر الإضافة، يقرأ كل جانب المفتاح كما تبيّن صفحة البدء السريع الخاصة به: local.properties على Android، و Secrets.xcconfig على iOS.
على iOS، أضف إمكانية App Attest (capability) إلى الهدف Runner: بها يُثبت تطبيقك تثبيته، ولا تُرفع التسجيلات التي يشاركها المتعلّمون من دونها (مشاركة التسجيلات).
معاينة: الاستدعاءات الأربعة بلغة Dart
معاينة، لم تُنشر بعد. هذه هي الواجهة المخطَّط لها للإضافة، لترى إلى أين تتّجه. لا شيء في هذه الصفحة يمكن تثبيته اليوم، وقد يتغيّر اسمٌ منها قبل الإصدار.
import 'package:quranlab_tajweedformer/quranlab_tajweedformer.dart';
Future<void> quickStart(void Function(String heard) show) async {
// your key; one client per process
final client = await TajweedClient.create('qlk_v1_...');
// the first run downloads and verifies the model
final model = await client.model(onProgress: (done, total) => print('$done / $total'));
// asks for the microphone itself; ends 1.5 s after the learner stops
const options = TajweedSessionOptions(endOnSilenceMs: 1500);
final session = await model.listen(options: options);
// every chunk: what the model heard so far
await for (final chunk in session.chunks) {
show(chunk.decoded.text);
}
}هذه هي الاستدعاءات الأربعة في كل حزمة SDK من Quran Lab.
- الميكروفون. يستخدم
model.listen()ميكروفون الـ SDK نفسه. على Android يطلب الـ SDK إذنRECORD_AUDIOبنفسه، وعلى iOS يحتاج التطبيق إلىNSMicrophoneUsageDescriptionفيios/Runner/Info.plist. وإذا رُفض الإذن، فالخطأ هوmicrophone_denied. - نهاية المحاولة. إذا ضُبط
endOnSilenceMs، تنتهي المحاولة من تلقاء نفسها حين يعقب الكلامَ صمتٌ بالمدة المحدّدة فيه: يحمل آخر مقطعdecoded.isFinal. ومن دون هذا الخيار، استدعِsession.finish()، الذي يُرجع رؤوس الإخراج (heads) لهذه المحاولة (heads.decoded()). - صوتك الخاص. يأخذ
model.session()الصوت الذي يدفعه تطبيقك إليه:session.push()معFloat32List، أوsession.pushInt16()معInt16List، بقيمةsampleRateفي خياراته (16000ما لم تحدّد غيرها، من8000إلى48000). - من دون ميكروفون. يمرّر
model.listenFrom(model.sampleClips.first)مقطعًا صوتيًا مرفقًا بالنموذج عبر المسار نفسه. - الأحداث. يخبرك
session.eventsبما جرى للمحاولة:TajweedSpeechStartedوTajweedSpeechEndedوTajweedInterruptedوTajweedResumedوTajweedBackendChangedوTajweedEnded. - الأخطاء. كل خطأ هو
TajweedError، وفيه رمز خطأ ثابت (code، وثوابته فيTajweedErrorCode)، والرسالة (message)، وسطر ما العمل (fix)، ورابط (docs) إلى صفحة الأخطاء. - مشاركة التسجيلات. يسأل الـ SDK المتعلّمين بنافذة Quran Lab الخاصة: على Android تعرضها الإضافة فوق نشاط Flutter (activity)، وعلى iOS يعرضها الـ SDK فوق متحكّم العرض (view controller) الظاهر في المقدّمة. وليس في تطبيقك ما يلزم تفعيله أو تعطيله. ويفتح
client.sharing.openSettings()شاشة إعدادات الـ SDK، لتضعها خلف صف في إعدادات تطبيقك (مشاركة التسجيلات).
يحمل كل مقطع chunk.decoded (text، tokens، words، settled، isFinal) و chunk.heads (المخرجات الخام التي اخترتها). وتشرح صفحة ابنِ ملاحظاتك بنفسك ما يعنيه كلٌّ منها.
تصبح الأسماء نهائية في README الحزمة يوم نشرها.