Orinj Структура на ефектите oreffect.jar

Orinj версия 9.0.0

Бележка: Тази страница не е за потребителите на Orinj, а за програмистите, които искат да създават ефекти за работа с цифрови сигнали за Orinj.

За сваляне

oreffect.jar

Този Java JAR файл се намира в папката "orinj" в инсталацията на Orinj. Дава двата интерфейса, които ефектите в Orinj трябва да осъществят в Java – EffectInterface и EffectPanelInterface.

• EffectInterface.java: Този интерфейс е самият ефект. Този интерфейс определя например, че един ефект в Orinj трябва да осъществи една функция "apply" ("приложи") с определен синтаксис, така че Orinj да може да изпрати буфери с данни за аудио към този ефект и този ефект може да бъде приложен към данните за аудио.
• EffectPanelInterface.java: Този интерфейс трябва да се осъществи от графичния интерфейс на ефекта. Самият графичен интерфейс трябва да съдържа контролите, с които потребителя може да работи за да промени ефекта. Този интерфейс определя например, че панела с графиките за ефекта трябва да осъществи функцията "updateData", така че Orinj да може да каже на ефекта да обнови контролите за потребителя със стойностите на ефекта.

Когато създаваш ефекти в Orinj, трябва да създадеш поне два класа в Java – един за ефекта и един за графиките на ефекта. Тези два класа трябва да осъществят съответно двата интерфейса по-горе.

Ефектите, които автоматизират един или повече от своите параметри, трябва също така да осъществят следния интерфейс.

• AutomationOwnerInterface: Този интерфейс дава достъп на Orinj до автоматизациите в ефекта.

Ефектите, които не предлагат автоматизации за никои от своите параметри, не трябва да осъществяват този интерфейс.

Останалите класове в този JAR са следните.

• Automation: Една автоматизация е сбирка от точки в две измерения, които представляват някакви стойности в различни времена. Ако един ефект например автоматизира един параметър за забавянето, който се измерва в милисекунди и има три точки (0, 0), (1, 100) и (2, 0), тогава параметърът за забавянето ще остане какъвто е на време 0, плавно ще се увеличи до същата стойност плюс 100 ms на време 1 секунда и след това ще се намали обратно до оригиналната си стойност на време 2 секунди. Една автоматизация също определя своя минимум, максимум, броя на цифрите след десетичната запетая, които трябва да се покажат, как стойностите трябва да се отбележат (например "ms" в този пример) и едно име (например "Автоматизация за забавянето").
• AutomationEvent: Едно събитие за автоматизацията се създава от собственика на автоматизацията (например ефекта), когато автоматизацията се активира или деактивира. Автоматизациите в ефектите на Orinj винаги са там, но могат да са активни, показани и използвани или не активни, не показани и не използвани.
• AutomationListener: Различни компоненти на Orinj ще слушат за събития за автоматизациите за да покажат или скрият автоматизации.
• AutomationPoint: Една точка в автоматизацията има две измерения, които определят стойността на автоматизацията (стойността y на точката) в някакво време (стойността x на точката).
• EffectChannels: Статични стойности за да се определят каналите в Orinj: ляв, десен или и двата. Orinj изпраща стойността на канала към всеки ефект със всеки буфер със звук. Ефектът тогава може да избере кой канал да преработи.
• EffectFont: Този клас съдържа статични шрифтове от клас java.awt.Font. При някои от кожите на Orinj, тези шрифтове ще бъдат променени от Orinj за да са същите, като шрифтовете на кожата. Можеш да използваш тези шрифтове за панела с графиките на твоя ефект, така че да изглежда както останалите части на Orinj. Не е задължително да използваш тези шрифтове.
• EffectGraph: Този клас съдържа цветове за графиките в Orinj. Може а използваш тези цветове за графики в ефектите. Не е задължително да използваш тези цветове.
• EffectSkin: Този клас показва дали текущата кожа е тъмна (със светли шрифтове и граници) или светла (с тъмни шрифтове и граници). Можеш да използваш тази стойност, но не е задължително да я използваш.
• ReadInterface: Това е един интерфейс, който се използва подобно на java.io.ObjectInputStream. Помага при четенето на параметрите на ефекта, запазени в сесии или лупинги или запазени за могат да се връщат промените.
• Undo: Всички ефекти (самите ефекти, а не панелите с техните графики) трябва да разширят този клас. Този клас съдържа една поредица от слушатели за събития и може да бъде използван за да се изпращат събития undo (за връщане на промените), които Orinj използва за да запази информация за промените в твоя ефект, които могат да бъдат върнати от потребителя.
• UndoEvent: Събитието, което трябва да се изпрати, така че Orinj да запази информацията, която може да бъде върната и да покаже едно съобщение за това в своите менюта.
• UndoListener: Един интерфейс, който се осъществява от слушателите за събития за връщане. Този интерфейс се осъществява от компоненти на Orinj, които ще слушат за събития, изпратени от ефектите.
• WorkingFolder: Този клас съдържа пътя към orinj.jar. Ефектите по-принцип не трябва да използват този клас. Ефектите в инсталацията на Orinj използват този клас за да получат информация за преводите на различни езици.
• WriteInterface: Това е един интерфейс, който трябва да се използва подобно на java.io.ObjectOutputStream. Помага при запазването на параметри на ефектите при запазването на сесии, лупинги или информация за връщане на промените.

Следното е допълнителна информация за трите интерфейса описани по-горе.

AutomationOwnerInterface.java

Само ефектите, които предлагат автоматизирани параметри, трябва да осъществяват този интерфейс. Следното са функциите на този интерфейс.

• public abstract int getNumAutomations(): Тази функция дава броя на автоматизираните параметри в ефекта.
• public abstract Automation getAutomation(int index): Тази функция връща автоматизацията с определения индекс. Orinj очаква, че автоматизациите са подредени с един индекс, който започва от 0. Ако в ефекта има три автоматизации, Orinj ще пита за автоматизациите с индекси 0, 1 и 2. Зависи от ефекта как автоматизациите ще са подредени.

EffectInterface.java

Всички ефекти в Orinj трябва да осъществят този интерфейс. Следното описва функциите в този интерфейс.

• public abstract boolean apply(int [] buffer, int [] controlbuffer, int channels, int channel, float samplingRate, double time, double timeStart, double timeEnd): Тази функция взема входните аудио данни и ги променя за да приложи ефекта.
• buffer – този буфер съдържа входните данни с аудио и също така се използва за да се запазят изходните данни с аудио от ефекта. Това е поредица от 32-битови цели числа със знак (тоест, 32-битови данни PCM, които са цели числа със знак) със стойности между Integer.MIN_VALUE и Integer.MAX_VALUE.
•  
• Този аргумент съдържа 32-битови данни PCM от цели числа със знак, независимо от пробната резолюция, която се използва в други части на Orinj. Това важи и за входните, и за изходните данни. Самият Orinj, а не ефекта, превръща данните с аудио в буфери с цели числа от 32 бита преди да изпрати тези данни с аудио към ефекта и превръща изхода от ефекта обратно в каквото се използва от звуковите устройства.
•  
• Данните с аудио в buffer може да са за един или два канал, както е определено от аргумента channels. С два канала, първото цяло число е първата проба за левия канал, следващото цяло число е първата проба за десния канал, следващото цяло число е втората проба за левия канал и така нататък.
•  
• buffer не съдържа всички аудио данни, които ще се изпратят към ефекта. По време на свиренето, данните с аудио се изпращат към ефекта на части. Самият ефект трябва да се справи с запазването и изхвърлянето на данни с аудио по начин, който работи за ефекта. Ехото в Orinj например използва предишни данни с аудио, защото текущите стойности на повторенията на ехото зависят от предишните стойности на сигнала. Това ехо запазва предишните аудио данни, използва ги и ги изхвърля, когато вече не са необходими (например, когато данните с аудио са доста далече в миналото за да се използват от ехото).
•  
• controlbuffer – контролния буфер трябва да се използва от ефекти, които позволяват странична връзка, като например един компресор със странична връзка. Един компресор със странична връзка променя динамиката на една писта в зависимост от динамиката на една втора писта. Данните с аудио, които се съдържат във втората писта, ще се изпратят към ефекта в този аргумент.
•  
• Един ефект, който използва този аргумент, трябва също да върне true в allowsSideChaining. Ако ефектът не позволява странични връзки, този аргумент може да е null и трябва да не се използва.
•  
• Orinj контролира коя писта се използва като контролна писта. Няма нужда да се осъществяват контроли в графичния интерфейс на ефекта за това. Orinj ще достави тези контроли, ако ефектът върне true в allowsSideChaining.
•  
• Ако controlbuffer не е null, тогава дължината на controlbuffer е същата, като дължината на buffer. Форматът на данните с аудио в controlbuffer е същият, като формата на данните с аудио в buffer.
•  
• channels – броя на аудио каналите в buffer.
• channel – каналът, към който този ефект се прилага. Възможни стойности са определени в EffectChannels.java и могат да са двата канала, левия или десния.
• samplingRate – пробната честота на аудиото в buffer.
• time – началното време на буферите за аудио (buffer и controlbuffer) в сесията, вълната или лупинга, който се свири, в секунди. Ако свиренето например започва на десетата секунда в многопистовата сесия, time ще бъде равно на 10 при първото повикване на тази функция.
•  
• Този аргумент обикновено се използва за да се изчислят текущите стойности на автоматизациите. Някои ефекти могат да се нуждаят от точното време на свирене. Един wah wah например ще звучи по добре ако трептенето му съвпада с ритъма на песента. Уа-уа-то тофава трябва да знае времето на свиренето. По принцип, ефекти, които използват нискочестотно трептене – трептене с честоти, които могат да се създават или възприемат от хората – вероятно се нуждаят от времето на свирене.
•  
• timeStart – началното време, след което ефектът трябва да се приложи, в секунди, след началото на сесията или вълната. Тази функция няма да се извика, ако звуковите буфери са извън интервала между timeEnd и timeStart.
• timeEnd – крайното време, преди което ефектът трябва да се приложи, в секунди, от началото на сесията или вълната.
•  
• Функцията връща true, ако няма грешки. Връща false, ако има грешки.
• public abstract boolean allowsSideChaining(): За да осъществиш тази функция, върни true, ако твоя ефект позволява странична връзка и false, ако не позволява.
• public abstract boolean startPlay(): Използвай тази функция за каквито и да са подготовки в началото на свиренето. Графичният еквилайзер в Orinj например използва тази функция за да изчисли своите честотни филтри (въпреки че тези филтри могат пак да бъдат изчислени по време на свиренето, ако потребителят промени контролите на еквилайзера). Тази функция връща true, ако няма грешки и false, ако има.
• public abstract void stopPlay(): Използвай тази функция за действията, които трябва да се извършат, когато свиренето спре. Внимавай с тази функция, защото свиренето може да продължи за малко даже и след като тази функция свърши, в зависимост от размера на буферите за аудио в Orinj. Не трябва например да използваш тази функция за да махаш запазените входни данни с аудио (по-скоро, изтрий тези данни когато свиренето започне следващия път). Много малко от ефектите в инсталацията на Orinj използват тази функция.
• public abstract boolean hasData(): Тази функция трябва да върне true, ако ефектът не е свършил своята работа и false, ако е. Представи си един прост дилей (виж Orinj Структура на ефектите Примерен дилей Delay.java). Един такъв ефект създава едно повторение на оригиналния сигнал. Даже и когато оригиналният сигнал е свършил (например след края на последната вълна в пистата), повторението на сигнала, което е създадено от ефекта, може да продължи за кратко време след това. Orinj първо ще провери дали има още оригинален сигнал. Ако не, ще запита ефекта дали самият той ще произведе сигнал. Ако да, ефектът ще бъде използван. Ако не, ефектът няма да бъде използван. Това е просто един начин да се спестят изчисления за да се направят ефектите по-бързи. За да създаде своето повторение, Примерният Дилей запазва част от оригиналния сигнал. След като оригиналният сигнал е свършил, Примерен Дилей ще върне true с тази функция само ако все още има запазена част от оригиналния сигнал. Това означава, че все още може да произведе края на повторения сигнал. Когато и запазената част на оригиналния сигнал е свършена, Примерен Дилей няма вече да може да произвежда повторения сигнал и ще върне false тук. Забележи, че винаги е безопасно просто да се върне false. Ако направиш това обаче, мокрият сигнал от твоя ефект може да спре преждевременно на края на вълната. Повечето от ефектите всъщност произвеждат едно забавяне в сигнала, което трябва да се вземе предвид.
• public abstract boolean readObject(ReadInterface stream): Тази функция и следващата функцията позволяват на Orinj да запази контролите на ефектите във файловете на сесията, лупингите или при връщането на промени в ефекта. Orinj очаква, че всеки обект (писти, ефекти, обвивки за амплитудата) осъществява собственото си запазване (т.е., стандартните методи за запазвана в Java чрез Serializable не се използват). Следното е (една опростена версия на) readObject в дилея в Orinj.

• public boolean readObject(ReadInterface ar)
• {
•    try
•    {
•       m_leftDelay = ar.readFloat();
•       m_rightDelay = ar.readFloat();
•       m_leftPolarity = ar.readBoolean();
•       m_rightPolarity = ar.readBoolean();
•       m_leftDecay = ar.readFloat();
•       m_rightDecay = ar.readFloat();
•       m_lockChannels = ar.readBoolean();
•    }
•    catch (IOException e)
•    {
•       System.out.println("Exception in Delay::readObject: " + e);
•       return false;
•    }
•    return true;
• }
•  
• Забележи, че можеш да запазиш и четеш не само контролите на ефектите, но и номера на версията на ефекта, която може да е независима от версията на Orinj. По този начин, можеш да имаш контрол върху версиите на твоя ефект.

• public abstract boolean writeObject(WriteInterface stream): Това е функцията, която Orinj използва за да чете ефектите в сесията на Orinj, в лупингите или за връщане на промени в ефектите. Тази функция трябва да бъде осъществена подобно на горната, но стойностите трябва да бъдат запазени, а не четени.
• public abstract void setLanguage(String languageCode): Осъществи тази функция, ако графиките на твоя ефект поддържат различни езици. Тази функция сменя текущия език на този, който е определен от languageCode. Аргументът languageCode е езика според ISO 639-2.

• В Orinj, текста на етикетите, подсказките и други подобни елементи се пази във файлове XML (виж например папката orinj/languages в твоята инсталация на Orinj). Можеш обаче да програмираш езиците по някакъв друг начин и не е задължително да използваш различни езици.

EffectPanelInterface.java

Графичния интерфейс за ефектите в Orinj обикновено развива класа javax.swing.JPanel и трябва да осъществи този интерфейс.

Ефектите в Orinj се изчисляват по време на свиренето и прозорците, които Orinj използва за да позволи на потребителя да промени контролите за ефектите не са модални. Тоест, потребителят може да работи с останалите части на Orinj докато прозореца за ефекта е отворен. В Orinj, всички прозорци за ефектите са стандартни. Самият прозорец (от клас JDialog) е вече осъществен и не трябва а го програмираш. Този прозорец съдържа:

• Един бутон Затвори (Close)
• Една контрола за пренебрегване на ефекта
• Една контрола за промяна на името на ефекта
• Една контрола за избор на предопределени настройки
• Бутони за запазване и изтриване на предопределени настройки
• Една контрола за избора на контролираща писта, ако ефекта позволява странична връзка.

Тези контроли са вече готови и не трябва да ги програмираш. Трябва само да създадеш контролите, които са специфични за ефекта. При дилея в Orinj например, тези контроли са забавянията, затихванията и полярността на левия и десния канал, както в примера по-горе. Когато създадеш самите контроли за ефекта, сложи ги в един клас, който удължава javax.swing.JPanel. Orinj ще вземе този панел и ще го сложи в един прозорец, който вече съдържа бутона Close и кутията за подминаване.

Интерфейсът EffectPanelInterface съдържа една единствена функция:

• public abstract void updateData(): Тази функция прави стойностите на контролите в панела за ефекта равни на стойностите на съответните данни в самия ефект.

Виж също:
Orinj Структура на ефектите