1. /*
  2. * This file is part of Beads. See http://www.beadsproject.net for all information.
  3. */
  4. package net.beadsproject.beads.ugens;
  6. import net.beadsproject.beads.core.AudioContext;
  7. import net.beadsproject.beads.core.Bead;
  8. import net.beadsproject.beads.core.UGen;
  9. import net.beadsproject.beads.data.Sample;
  10. import net.beadsproject.beads.data.SampleManager;
  12. /**
  13. * SamplePlayer plays back a {@link Sample}. Playback rate and loop points can be controlled by {@link UGen}s. The playback point in the {@link Sample} can also be directly controlled from {@link UGen} to perform scrubbing. The player can be set to a number of different loop modes. If constructed with a {@link Sample} argument, the number of outputs of SamplePlayer is determined by the number of channels of the {@link Sample}. {@link Sample} playback can use either linear or cubic interpolation.
  14. *
  15. * @author ollie
  16. */
  17. public class SamplePlayer extends UGen {
  19. /**
  20. * The Enum InterpolationType.
  21. */
  22. public static enum InterpolationType {
  24. /** Use linear interpolation. */
  25. LINEAR,
  27. /** Use cubic interpolation. */
  28. CUBIC
  29. };
  31. /**
  32. * The Enum LoopType.
  33. */
  34. public static enum LoopType {
  36. /** Play forwards without looping. */
  37. NO_LOOP_FORWARDS,
  39. /** Play backwards without looping. */
  40. NO_LOOP_BACKWARDS,
  42. /** Play forwards with loop. */
  43. LOOP_FORWARDS,
  45. /** Play backwards with loop. */
  46. LOOP_BACKWARDS,
  48. /** Loop alternately forwards and backwards. */
  49. LOOP_ALTERNATING
  51. };
  53. /** The Sample. */
  54. protected Sample buffer;
  56. /** The sample rate, determined by the Sample. */
  57. protected float sampleRate;
  59. /** The position in milliseconds. */
  60. protected double position;
  62. /** The last changed position, used to determine if the position envelope is in use. */
  63. protected double lastChangedPosition;
  65. /** The position envelope. */
  66. protected UGen positionEnvelope;
  68. /** The rate envelope. */
  69. protected UGen rateEnvelope;
  71. /** The millisecond position increment per sample. Calculated from the ratio of the {@link AudioContext}'s sample rate and the {@link Sample}'s sample rate. */
  72. protected double positionIncrement;
  74. /** Flag for alternating loop mode to determine if playback is in forward or reverse phase. */
  75. protected boolean forwards;
  77. /** The interpolation type. */
  78. protected InterpolationType interpolationType;
  80. /** The loop start envelope. */
  81. protected UGen loopStartEnvelope;
  83. /** The loop end envelope. */
  84. protected UGen loopEndEnvelope;
  86. /** The loop type. */
  87. protected LoopType loopType;
  89. /** The loop cross fade in milliseconds. */
  90. protected float loopCrossFade; //TODO loop crossfade behaviour
  92. /** Flag to determine whether playback starts at the beginning of the sample or at the beginning of the loop. */
  93. protected boolean startLoop; //TODO behaviour such that if you're outside the loop points you immediately pop inside them.
  95. /** Flag to determine whether the SamplePlayer should kill itself when it gets to the end of the Sample. */
  96. protected boolean killOnEnd;
  98. /** The rate. Calculated and used internally from the rate envelope. */
  99. protected float rate;
  101. /** The loop start. Calculated and used internally from the loop start envelope. */
  102. protected float loopStart;
  104. /** The loop end. Calculated and used internally from the loop end envelope. */
  105. protected float loopEnd;
  107. /**
  108. * Instantiates a new SamplePlayer with given number of outputs.
  109. *
  110. * @param context the AudioContext.
  111. * @param outs the number of outputs.
  112. */
  113. public SamplePlayer(AudioContext context, int outs) {
  114. super(context, outs);
  115. rateEnvelope = new Static(context, 1.0f);
  116. positionEnvelope = new Static(context, 0.0f);
  117. interpolationType = InterpolationType.LINEAR;
  118. loopType = LoopType.NO_LOOP_FORWARDS;
  119. forwards = true;
  120. killOnEnd = true;
  121. loopStartEnvelope = new Static(context, 0.0f);
  122. loopEndEnvelope = new Static(context, 0.0f);
  123. }
  125. /**
  126. * Instantiates a new SamplePlayer with given Sample. Number of outputs is determined by number of channels in Sample.
  127. *
  128. * @param context the AudioContext.
  129. * @param buffer the Sample.
  130. */
  131. public SamplePlayer(AudioContext context, Sample buffer) {
  132. this(context, buffer.nChannels);
  133. setBuffer(buffer);
  134. loopEndEnvelope.setValue(buffer.length);
  135. }
  137. /**
  138. * Sets the Sample.
  139. *
  140. * @param buffer the new Sample.
  141. */
  142. public void setBuffer(Sample buffer) {
  143. this.buffer = buffer;
  144. sampleRate = buffer.audioFormat.getSampleRate();
  145. updatePositionIncrement();
  146. }
  148. /**
  149. * Gets the Sample.
  150. *
  151. * @return the Sample.
  152. */
  153. public Sample getBuffer() {
  154. return buffer;
  155. }
  157. /**
  158. * Sets the playback position to the end of the Sample.
  159. */
  160. public void setToEnd() {
  161. position = buffer.length;
  162. }
  164. /**
  165. * Determines whether the playback position is within the loop points.
  166. *
  167. * @return true if the playback position is within the loop points.
  168. */
  169. public boolean inLoop() {
  170. return position < Math.max(loopStart, loopEnd) && position > Math.min(loopStart, loopEnd);
  171. }
  173. /**
  174. * Sets the playback position to the loop start point.
  175. */
  176. public void setToLoopStart() {
  177. position = Math.min(loopStart, loopEnd);
  178. forwards = (rate > 0);
  179. }
  181. /**
  182. * Starts the sample at the given position.
  183. *
  184. * @param msPosition the position in milliseconds.
  185. */
  186. public void start(float msPosition) {
  187. position = msPosition;
  188. start();
  189. }
  191. /**
  192. * Resets the position to the start of the Sample.
  193. */
  194. public void reset() {
  195. position = 0f;
  196. }
  198. /**
  199. * Gets the playback position.
  200. *
  201. * @return the position in milliseconds.
  202. */
  203. public double getPosition() {
  204. return position;
  205. }
  207. /**
  208. * Sets the playback position.
  209. *
  210. * @param position the new position in milliseconds.
  211. */
  212. public void setPosition(double position) {
  213. this.position = position;
  214. }
  216. /**
  217. * Gets the position envelope.
  218. *
  219. * @return the position envelope.
  220. */
  221. public UGen getPositionEnvelope() {
  222. return positionEnvelope;
  223. }
  225. /**
  226. * Sets the position envelope. Setting the position envelope means that the position is then controlled by this envelope. If the envelope is null, or unchanging, the position continues to be modified by the SamplePlayer's internal playback or by calls to change the position.
  227. *
  228. * @param positionEnvelope the new position envelope.
  229. */
  230. public void setPositionEnvelope(UGen positionEnvelope) {
  231. this.positionEnvelope = positionEnvelope;
  232. }
  234. /**
  235. * Gets the rate envelope.
  236. *
  237. * @return the rate envelope.
  238. */
  239. public UGen getRateEnvelope() {
  240. return rateEnvelope;
  241. }
  243. /**
  244. * Sets the rate envelope.
  245. *
  246. * @param rateEnvelope the new rate envelope.
  247. */
  248. public void setRateEnvelope(UGen rateEnvelope) {
  249. this.rateEnvelope = rateEnvelope;
  250. }
  252. /**
  253. * Updates the position increment. Called whenever the {@link Sample}'s sample rate or the {@link AudioContext}'s sample rate is modified.
  254. */
  255. private void updatePositionIncrement() {
  256. positionIncrement = context.samplesToMs(sampleRate / context.getSampleRate());
  257. }
  259. /**
  260. * Gets the interpolation type.
  261. *
  262. * @return the interpolation type.
  263. */
  264. public InterpolationType getInterpolationType() {
  265. return interpolationType;
  266. }
  268. /**
  269. * Sets the interpolation type.
  270. *
  271. * @param interpolationType the new interpolation type.
  272. */
  273. public void setInterpolationType(InterpolationType interpolationType) {
  274. this.interpolationType = interpolationType;
  275. }
  277. /**
  278. * Gets the loop cross fade.
  279. *
  280. * @return the loop cross fade in milliseconds.
  281. */
  282. public float getLoopCrossFade() {
  283. return loopCrossFade;
  284. }
  286. /**
  287. * Sets the loop cross fade.
  288. *
  289. * @param loopCrossFade the new loop cross fade in milliseconds.
  290. */
  291. public void setLoopCrossFade(float loopCrossFade) {
  292. this.loopCrossFade = loopCrossFade;
  293. }
  295. /**
  296. * Gets the loop end envelope.
  297. *
  298. * @return the loop end envelope.
  299. */
  300. public UGen getLoopEndEnvelope() {
  301. return loopEndEnvelope;
  302. }
  304. /**
  305. * Sets the loop end envelope.
  306. *
  307. * @param loopEndEnvelope the new loop end envelope.
  308. */
  309. public void setLoopEndEnvelope(UGen loopEndEnvelope) {
  310. this.loopEndEnvelope = loopEndEnvelope;
  311. }
  313. /**
  314. * Gets the loop start envelope.
  315. *
  316. * @return the loop start envelope
  317. */
  318. public UGen getLoopStartEnvelope() {
  319. return loopStartEnvelope;
  320. }
  322. /**
  323. * Sets the loop start envelope.
  324. *
  325. * @param loopStartEnvelope the new loop start envelope.
  326. */
  327. public void setLoopStartEnvelope(UGen loopStartEnvelope) {
  328. this.loopStartEnvelope = loopStartEnvelope;
  329. }
  331. /**
  332. * Sets both loop points to static values as fractions of the Sample length.
  333. *
  334. * @param start the start value, as fraction of the Sample length.
  335. * @param end the end value, as fraction of the Sample length.
  336. */
  337. public void setLoopPointsFraction(float start, float end) {
  338. loopStartEnvelope = new Static(context, start * (float)buffer.length);
  339. loopEndEnvelope = new Static(context, end * (float)buffer.length);
  340. }
  342. /**
  343. * Gets the loop type.
  344. *
  345. * @return the loop type.
  346. */
  347. public LoopType getLoopType() {
  348. return loopType;
  349. }
  351. /**
  352. * Sets the loop type.
  353. *
  354. * @param loopType the new loop type.
  355. */
  356. public void setLoopType(LoopType loopType) {
  357. this.loopType = loopType;
  358. if(loopType != LoopType.LOOP_ALTERNATING) {
  359. if(loopType == LoopType.LOOP_FORWARDS || loopType == LoopType.NO_LOOP_FORWARDS) {
  360. forwards = true;
  361. } else {
  362. forwards = false;
  363. }
  364. }
  365. }
  367. /**
  368. * Gets the sample rate.
  369. *
  370. * @return the sample rate, in samples per second.
  371. */
  372. public float getSampleRate() {
  373. return sampleRate;
  374. }
  376. /* (non-Javadoc)
  377. * @see com.olliebown.beads.core.UGen#calculateBuffer()
  378. */
  379. @Override
  380. public void calculateBuffer() {
  381. if(buffer != null) {
  382. rateEnvelope.update();
  383. positionEnvelope.update();
  384. loopStartEnvelope.update();
  385. loopEndEnvelope.update();
  386. for (int i = 0; i < bufferSize; i++) {
  387. //calculate the samples
  388. double posInSamples = buffer.msToSamples((float)position);
  389. int currentSample = (int) posInSamples;
  390. float fractionOffset = (float)(posInSamples - currentSample);
  391. float[] frame = null;
  392. switch (interpolationType) {
  393. case LINEAR:
  394. frame = buffer.getFrameLinear(currentSample, fractionOffset);
  395. break;
  396. case CUBIC:
  397. frame = buffer.getFrameCubic(currentSample, fractionOffset);
  398. break;
  399. }
  400. for (int j = 0; j < outs; j++) {
  401. bufOut[j][i] = frame[j % buffer.nChannels];
  402. }
  403. //update the position, loop state, direction
  404. calculateNextPosition(i);
  405. if(isPaused()) {
  406. //make sure to zero the remaining outs
  407. while(i < bufferSize) {
  408. for (int j = 0; j < outs; j++) {
  409. bufOut[j][i] = 0.0f;
  410. }
  411. i++;
  412. }
  413. break;
  414. }
  415. }
  416. }
  417. }
  419. /**
  420. * Sets/unsets option for SamplePlayer to kill itself when it reaches the end of the Sample it is playing.
  421. *
  422. * @param killOnEnd true to kill on end.
  423. */
  424. public void setKillOnEnd(boolean killOnEnd) {
  425. this.killOnEnd = killOnEnd;
  426. }
  428. /**
  429. * Determines whether this SamplePlayer will kill itself at the end of the Sample it is playing.
  430. *
  431. * @return true of SamplePlayer will kill itself at the end of the Sample it is playing.
  432. */
  433. public boolean getKillOnEnd() {
  434. return(killOnEnd);
  435. }
  437. /**
  438. * Called when at the end of the Sample, assuming the loop mode is non-looping, or beginning, if the SamplePlayer is playing backwards..
  439. */
  440. private void atEnd () {
  441. if (killOnEnd) {
  442. kill();
  443. }
  444. else {
  445. pause(true);
  446. }
  447. }
  449. /**
  450. * Re trigger the SamplePlayer from the beginning.
  451. */
  452. public void reTrigger() {
  453. reset();
  454. this.pause(false);
  455. }
  457. /**
  458. * Used at each sample in the perform routine to determine the next playback position.
  459. *
  460. * @param i the index within the buffer loop.
  461. */
  462. protected void calculateNextPosition(int i) {
  463. rate = rateEnvelope.getValue(0, i);
  464. loopStart = loopStartEnvelope.getValue(0, i);
  465. loopEnd = loopEndEnvelope.getValue(0, i);
  466. if(lastChangedPosition != positionEnvelope.getValue(0, i)) {
  467. position = positionEnvelope.getValue(0, i);
  468. lastChangedPosition = position;
  469. }
  470. switch(loopType) {
  471. case NO_LOOP_FORWARDS:
  472. position += positionIncrement * rate;
  473. if(position > buffer.length || position < 0) atEnd();
  474. break;
  475. case NO_LOOP_BACKWARDS:
  476. position -= positionIncrement * rate;
  477. if(position > buffer.length || position < 0) atEnd();
  478. break;
  479. case LOOP_FORWARDS:
  480. position += positionIncrement * rate;
  481. if(rate > 0 && position > Math.max(loopStart, loopEnd)) {
  482. position = Math.min(loopStart, loopEnd);
  483. } else if(rate < 0 && position < Math.min(loopStart, loopEnd)) {
  484. position = Math.max(loopStart, loopEnd);
  485. }
  486. break;
  487. case LOOP_BACKWARDS:
  488. position -= positionIncrement * rate;
  489. if(rate > 0 && position < Math.min(loopStart, loopEnd)) {
  490. position = Math.max(loopStart, loopEnd);
  491. } else if(rate < 0 && position > Math.max(loopStart, loopEnd)) {
  492. position = Math.min(loopStart, loopEnd);
  493. }
  494. break;
  495. case LOOP_ALTERNATING:
  496. position += forwards ? positionIncrement * rate : -positionIncrement * rate;
  497. if(forwards ^ (rate < 0)) {
  498. if(position > Math.max(loopStart, loopEnd)) {
  499. forwards = (rate < 0);
  500. position = 2 * Math.max(loopStart, loopEnd) - position;
  501. }
  502. } else if(position < Math.min(loopStart, loopEnd)) {
  503. forwards = (rate > 0);
  504. position = 2 * Math.min(loopStart, loopEnd) - position;
  505. }
  506. break;
  507. }
  508. }
  511. }